@devslab/site-kit 0.14.1 → 0.15.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@devslab/site-kit",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Strict i18n, SEO/GEO, and Solid public-site shells for DevsLab products",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "sideEffects": [
     "./styles.css",
-    "./site-sections.css"
+    "./site-sections.css",
+    "./fonts.css"
   ],
   "repository": {
     "type": "git",
@@ -21,11 +22,13 @@
   "files": [
     "dist",
     "flags",
+    "fonts",
     "src/core",
     "src/tanstack-start.mjs",
     "src/tanstack-start.d.mts",
     "styles.css",
     "site-sections.css",
+    "fonts.css",
     "README.md",
     "README.ko.md"
   ],
@@ -57,10 +60,12 @@
       "import": "./src/tanstack-start.mjs"
     },
     "./styles.css": "./styles.css",
-    "./site-sections.css": "./site-sections.css"
+    "./site-sections.css": "./site-sections.css",
+    "./fonts.css": "./fonts.css",
+    "./fonts/*": "./fonts/*"
   },
   "dependencies": {
-    "@devslab/dds-solid": "0.14.1"
+    "@devslab/dds-solid": "0.15.0"
   },
   "peerDependencies": {
     "@tanstack/solid-router": "1.170.30",
@@ -102,7 +107,7 @@
   ],
   "scripts": {
     "build": "vite build && vite build --config vite.server.config.ts && tsc -p tsconfig.build.json --emitDeclarationOnly",
-    "check": "node scripts/build-flags.mjs --check && tsc -p tsconfig.json --noEmit && tsc -p fixtures/bundle-probe/tsconfig.json && node scripts/check-client-bundle.mjs",
+    "check": "node scripts/build-flags.mjs --check && node scripts/build-fonts.mjs --check && tsc -p tsconfig.json --noEmit && tsc -p fixtures/bundle-probe/tsconfig.json && node scripts/check-client-bundle.mjs",
     "test": "vitest run --config vitest.config.ts && vitest run --config vitest.ssr.config.ts",
     "test:a11y": "vitest run --config vitest.config.ts src/solid/__tests__/a11y.test.tsx",
     "test:worker": "wrangler deploy --dry-run --config fixtures/worker/wrangler.jsonc --outdir dist-worker"

package/src/core/fonts.d.mts

@@ -0,0 +1,5 @@
+/** Package-relative path of Geist's Latin subset — the one family face every page fetches, so the one worth preloading (D-033). */
+export declare const FAMILY_FONT_PRELOAD_FILE: "fonts/geist/geist-latin-wght-normal.woff2";
+export interface FontPreloadLink { rel: "preload"; href: string; as: "font"; type: "font/woff2"; crossorigin: "anonymous" }
+/** `<link rel="preload" as="font">` descriptors. Each href is a same-origin path ending in .woff2; anything else throws RangeError. */
+export declare function fontPreloadLinks(hrefs: string | readonly string[]): FontPreloadLink[];

package/src/core/fonts.mjs

@@ -0,0 +1,39 @@
+/**
+ * Preload links for the family font (D-033). The faces themselves ship as
+ * `@devslab/site-kit/fonts.css` + `fonts/**`; this module only builds the
+ * `<link rel="preload">` a page head may add for the face every page needs.
+ */
+
+/**
+ * Package-relative path of the face worth preloading: Geist's Latin subset.
+ * Every family page draws Latin (digits, brand names, the language menu), so
+ * it is the one file a page always fetches; Pretendard's 92 Korean subsets
+ * depend on the text and are left to unicode-range.
+ *
+ * A Vite app imports it with `?url`, which yields the same hashed
+ * `/assets/*` URL the stylesheet's url() becomes:
+ *   import geistLatin from "@devslab/site-kit/fonts/geist/geist-latin-wght-normal.woff2?url";
+ */
+export const FAMILY_FONT_PRELOAD_FILE = "fonts/geist/geist-latin-wght-normal.woff2";
+
+const SAME_ORIGIN_PATH = /^\/(?!\/)/;
+
+/**
+ * `<link rel="preload" as="font">` descriptors, same shape as
+ * toTanStackHead's `links`. Each href must be a same-origin absolute path —
+ * the CSP is `font-src 'self'`, so a URL on another origin (or a data: URI)
+ * would be blocked anyway and the preload would only waste a request.
+ * `crossorigin` is required even on the same origin: fonts are fetched in
+ * CORS mode, and a preload without it is not reused by the @font-face fetch.
+ */
+export function fontPreloadLinks(hrefs) {
+  const list = typeof hrefs === "string" ? [hrefs] : [...(hrefs ?? [])];
+  return list.map((href) => {
+    const value = String(href);
+    if (!SAME_ORIGIN_PATH.test(value)) {
+      throw new RangeError(`fontPreloadLinks takes same-origin paths ("/assets/…"), not ${JSON.stringify(value)}: a product serves its own fonts`);
+    }
+    if (!/\.woff2(?:[?#].*)?$/.test(value)) throw new RangeError(`fontPreloadLinks preloads woff2 files only: ${JSON.stringify(value)}`);
+    return { rel: "preload", href: value, as: "font", type: "font/woff2", crossorigin: "anonymous" };
+  });
+}

package/src/core/index.d.mts

@@ -4,3 +4,4 @@ export * from "./seo.mjs";
 export * from "./geo.mjs";
 export * from "./publisher.mjs";
 export * from "./gtm.mjs";
+export * from "./fonts.mjs";

package/src/core/index.mjs

@@ -4,3 +4,4 @@ export { BRAND_ICON_FILES, ROBOTS_USER_AGENTS, brandIconLinks, buildMetadata, bu
 export { VerifiedFactRegistry, buildVerifiedJsonLd, renderLlmsTxt } from "./geo.mjs";
 export { definePublisher, buildPublisher, serializeJsonLd, renderPublisherHtml } from "./publisher.mjs";
 export { GTM_CONTAINER_ID_PATTERN, GTM_CSP_SOURCES, gtmHeadScript, gtmNoscriptIframe } from "./gtm.mjs";
+export { FAMILY_FONT_PRELOAD_FILE, fontPreloadLinks } from "./fonts.mjs";

package/src/tanstack-start.d.mts

@@ -8,9 +8,10 @@ import type { SiteLocale } from "./core/locales.mjs";
  */
 /**
  * `icons: true` appends brandIconLinks() (the /brand default); an object passes its options through. Omitted, no icon links are emitted.
+ * `fontPreload` appends fontPreloadLinks(fontPreload) — the same-origin URL(s) the product's bundler gave the family face, e.g. Geist Latin imported with `?url` (D-033). Omitted, no preload links are emitted.
  * `gtm` adds Google Tag Manager's head loader for that container id as `scripts[0]`; omitted or `undefined` (a route without Tag Manager), the result has no `scripts` key.
  */
-export interface TanStackHeadOptions { icons?: boolean | { basePath?: string }; gtm?: string | undefined }
+export interface TanStackHeadOptions { icons?: boolean | { basePath?: string }; fontPreload?: string | readonly string[] | undefined; gtm?: string | undefined }
 /** A route `head().scripts` entry: the loader body only. The router adds `ssr.nonce` when it renders the tag. Throws RangeError for a malformed id. */
 export interface GtmHeadEntry { children: string }
 export declare function gtmHeadEntry(containerId: string): GtmHeadEntry;

package/src/tanstack-start.mjs

@@ -1,5 +1,6 @@
 import { brandIconLinks } from "./core/seo.mjs";
 import { gtmHeadScript } from "./core/gtm.mjs";
+import { fontPreloadLinks } from "./core/fonts.mjs";
 
 /**
  * A route `head().scripts` entry that loads Google Tag Manager (D-031).
@@ -21,6 +22,8 @@ export function gtmHeadEntry(containerId) {
 // is worse than one that links none. `true` takes the /brand default.
 // `gtm` is opt-in the same way, and per route: the product decides which
 // pages carry Tag Manager (public marketing and legal pages, not consoles).
+// `fontPreload` is opt-in too: only the product knows the hashed URL its
+// bundler gave the face (D-033). Appended after the icons.
 export function toTanStackHead(metadata, options = {}) {
   const icons = options.icons === true ? brandIconLinks() : options.icons ? brandIconLinks(options.icons) : [];
   const head = {
@@ -43,6 +46,7 @@ export function toTanStackHead(metadata, options = {}) {
       { rel: "canonical", href: metadata.canonical },
       ...metadata.alternates.map(({ hreflang, href }) => ({ rel: "alternate", hreflang, href })),
       ...icons,
+      ...(options.fontPreload === undefined ? [] : fontPreloadLinks(options.fontPreload)),
     ],
   };
   if (options.gtm !== undefined) head.scripts = [gtmHeadEntry(options.gtm)];