@jant/core 0.6.16 → 0.7.0

package/src/ui/feed/__tests__/timeline-cards.test.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import type { Context } from "hono";
 import { renderToString } from "hono/jsx/dom/server";
 import { describe, expect, it } from "vitest";
+import { readComponentCss } from "../../../__tests__/helpers/component-css.js";
 import type { MediaView, PostView } from "../../../types.js";
 import { I18nProvider } from "../../../i18n/context.js";
 import { createI18n } from "../../../i18n/i18n.js";
@@ -50,11 +51,13 @@ function renderWithI18n(
     | ReturnType<typeof NoteCard>
     | ReturnType<typeof LinkCard>
     | ReturnType<typeof QuoteCard>,
+  isAuthenticated = true,
 ) {
   const i18n = createI18n("en");
   const c = {
     get(key: string) {
       if (key === "i18n") return i18n;
+      if (key === "isAuthenticated") return isAuthenticated;
       return undefined;
     },
   } as unknown as Context;
@@ -91,6 +94,274 @@ describe("timeline cards", () => {
     expect(detailHtml).not.toContain("feed-card");
   });
 
+  it("keeps the link preview above the commentary in every mode", () => {
+    const post = createPostView({
+      format: "link",
+      previewImageUrl: "https://example.com/preview.jpg",
+      previewKind: "video",
+      previewProvider: "youtube",
+    });
+
+    for (const mode of ["feed", "detail"] as const) {
+      const html = renderWithI18n(LinkCard({ post, mode }));
+
+      // The preview is part of the reference, so commentary follows it —
+      // detail used to invert this and read as a note about nothing.
+      expect(html.indexOf('class="link-preview"')).toBeGreaterThan(-1);
+      expect(html.indexOf('class="link-preview"')).toBeLessThan(
+        html.indexOf("data-post-body"),
+      );
+      expect(html.indexOf("feed-link-title")).toBeLessThan(
+        html.indexOf('class="link-preview"'),
+      );
+    }
+  });
+
+  it("marks a link post's referenced article as u-bookmark-of, never as the entry's own u-url", () => {
+    const post = createPostView({ format: "link" });
+
+    const feedHtml = renderWithI18n(LinkCard({ post, mode: "feed" }));
+    const compactHtml = renderWithI18n(LinkCard({ post, mode: "compact" }));
+    const detailHtml = renderWithI18n(LinkCard({ post, mode: "detail" }));
+
+    for (const html of [feedHtml, compactHtml, detailHtml]) {
+      expect(html).toContain(
+        '<a href="https://example.com/article" class="u-bookmark-of feed-link-title-link"',
+      );
+    }
+
+    // The entry's own URL is the permalink, and it is emitted exactly once —
+    // a second `u-url` on the referenced article would make parsers read that
+    // article as this post.
+    expect(feedHtml.match(/u-url/g)).toHaveLength(1);
+    expect(detailHtml.match(/u-url/g)).toHaveLength(1);
+    expect(feedHtml).toContain('class="u-url post-footer-link"');
+    expect(detailHtml).toContain('class="u-url post-footer-link"');
+  });
+
+  it("omits u-bookmark-of when a link post has no referenced article", () => {
+    const post = createPostView({ format: "link", url: undefined });
+
+    const feedHtml = renderWithI18n(LinkCard({ post, mode: "feed" }));
+    const detailHtml = renderWithI18n(LinkCard({ post, mode: "detail" }));
+
+    // The title falls back to the permalink; a post does not bookmark itself.
+    for (const html of [feedHtml, detailHtml]) {
+      expect(html).toContain('<a href="/post-1" class="feed-link-title-link"');
+      expect(html).not.toContain("u-bookmark-of");
+      expect(html.match(/u-url/g)).toHaveLength(1);
+    }
+  });
+
+  it("scopes a quote post's citation to an h-cite and keeps e-content on the commentary", () => {
+    const post = createPostView({ format: "quote" });
+
+    const feedHtml = renderWithI18n(QuoteCard({ post, mode: "feed" }));
+    const detailHtml = renderWithI18n(QuoteCard({ post, mode: "detail" }));
+
+    for (const html of [feedHtml, detailHtml]) {
+      expect(html).toContain('<figure class="feed-quote-cite h-cite">');
+      // The quotation is the citation's content, not the entry's.
+      expect(html).toContain('class="p-content feed-quote-content');
+      expect(html).not.toContain("e-content feed-quote-content");
+      expect(html).toContain('class="e-content feed-quote-commentary prose');
+
+      // Source URL and attribution belong to the cited work, so they have to
+      // sit inside the h-cite — outside it they would land on the h-entry.
+      const cite = html.slice(
+        html.indexOf('<figure class="feed-quote-cite h-cite">'),
+        html.indexOf("</figure>"),
+      );
+      expect(cite).toContain(
+        '<a href="https://example.com/article" class="u-url p-name feed-quote-source"',
+      );
+      expect(cite).toContain('<figcaption class="feed-quote-attribution">');
+    }
+  });
+
+  it("keeps a quote attribution without a source link addressable as p-name", () => {
+    const post = createPostView({ format: "quote", url: undefined });
+
+    const feedHtml = renderWithI18n(QuoteCard({ post, mode: "feed" }));
+
+    expect(feedHtml).toContain('<span class="p-name">Card title</span>');
+    expect(feedHtml.match(/u-url/g)).toHaveLength(1);
+  });
+
+  it("leaves note card microformats untouched", () => {
+    const post = createPostView({ format: "note" });
+
+    const feedHtml = renderWithI18n(NoteCard({ post, mode: "feed" }));
+    const detailHtml = renderWithI18n(NoteCard({ post, mode: "detail" }));
+
+    expect(feedHtml).toContain('<h2 class="p-name feed-note-title">');
+    expect(feedHtml).toContain('<a href="/post-1" class="hover:underline"');
+    expect(feedHtml).toContain('class="e-content prose');
+    expect(feedHtml).not.toContain("u-bookmark-of");
+    expect(feedHtml).not.toContain("h-cite");
+
+    expect(detailHtml).toContain('<h1 class="p-name post-detail-title">');
+    expect(detailHtml).toContain('class="u-url post-header-meta-link"');
+    expect(detailHtml).toContain('class="e-content prose post-detail-body"');
+    expect(detailHtml).not.toContain("u-bookmark-of");
+    expect(detailHtml).not.toContain("h-cite");
+  });
+
+  it("gives every card exactly one u-url, pointing at its permalink", () => {
+    // A titled note's heading used to link the permalink as a second `u-url`.
+    // Same value as the footer's, so no parser read the wrong post — but the
+    // entry's URL is one fact, and the footer is where all three cards state it.
+    const cards = [
+      NoteCard({ post: createPostView({ format: "note" }), mode: "feed" }),
+      NoteCard({ post: createPostView({ format: "note" }), mode: "detail" }),
+      NoteCard({
+        post: createPostView({ format: "note", title: undefined }),
+        mode: "feed",
+      }),
+      LinkCard({ post: createPostView({ format: "link" }), mode: "feed" }),
+      LinkCard({ post: createPostView({ format: "link" }), mode: "detail" }),
+      QuoteCard({ post: createPostView({ format: "quote" }), mode: "feed" }),
+      QuoteCard({ post: createPostView({ format: "quote" }), mode: "detail" }),
+    ];
+
+    for (const card of cards) {
+      // A quote's source link is a `u-url` too, but it belongs to the nested
+      // h-cite. Drop the citation before counting what the entry claims.
+      const entry = renderWithI18n(card).replace(
+        /<figure class="feed-quote-cite h-cite">[\s\S]*?<\/figure>/,
+        "",
+      );
+      expect(entry.match(/u-url/g)).toHaveLength(1);
+      expect(entry).toMatch(/<a href="\/post-1" class="u-url /);
+    }
+  });
+
+  it("states empty content outright when a card has no name and nothing to say", () => {
+    // The author's card carries every status badge in the DOM, hidden with
+    // CSS, which a microformats parser does not run. With no `p-name` and no
+    // `e-content` to go on, it names the entry after whatever text it finds —
+    // the badge labels. An explicit empty `e-content` says what is true and
+    // stops that.
+    const empty = { title: undefined, bodyHtml: undefined, media: [] };
+
+    for (const mode of ["feed", "detail", "compact"] as const) {
+      const cards = {
+        note: NoteCard({
+          post: createPostView({ format: "note", ...empty }),
+          mode,
+        }),
+        link: LinkCard({
+          post: createPostView({ format: "link", ...empty }),
+          mode,
+        }),
+        quote: QuoteCard({
+          post: createPostView({
+            format: "quote",
+            ...empty,
+            quoteText: undefined,
+            url: undefined,
+          }),
+          mode,
+        }),
+      };
+      for (const [format, card] of Object.entries(cards)) {
+        const html = renderWithI18n(card);
+        expect(`${format}/${mode}: ${html}`).toContain(
+          '<div class="e-content"></div>',
+        );
+      }
+    }
+  });
+
+  it("keeps stray h-* utilities out of post markup", () => {
+    // A microformats2 parser reads every `h-`-prefixed class as a microformat
+    // root, so a Tailwind height utility inside a card becomes a phantom child
+    // microformat on the entry. Only real roots may appear.
+    const withMedia = createPostView({
+      format: "note",
+      media: [createMediaView(), createMediaView({ id: "media-2" })],
+    });
+    const cards = {
+      "note with one image": NoteCard({
+        post: { ...withMedia, media: [createMediaView()] },
+        mode: "feed",
+      }),
+      "note with a gallery": NoteCard({ post: withMedia, mode: "feed" }),
+      "link post": LinkCard({
+        post: createPostView({ format: "link" }),
+        mode: "detail",
+      }),
+      "quote post": QuoteCard({
+        post: createPostView({ format: "quote" }),
+        mode: "feed",
+      }),
+    };
+
+    for (const [label, card] of Object.entries(cards)) {
+      const html = renderWithI18n(card);
+      const roots = [...html.matchAll(/class="([^"]*)"/g)]
+        .flatMap((m) => m[1].split(/\s+/))
+        .filter((c) => /^h-/.test(c));
+      const unexpected = roots.filter((c) => c !== "h-entry" && c !== "h-cite");
+      expect(`${label}: ${unexpected.join(", ")}`).toBe(`${label}: `);
+    }
+  });
+
+  it("omits the empty content marker when the card carries a name or content", () => {
+    const cards = {
+      "titled note": NoteCard({
+        post: createPostView({ format: "note", bodyHtml: undefined }),
+        mode: "feed",
+      }),
+      "untitled note with a body": NoteCard({
+        post: createPostView({ format: "note", title: undefined }),
+        mode: "feed",
+      }),
+      "titled link": LinkCard({
+        post: createPostView({ format: "link", bodyHtml: undefined }),
+        mode: "feed",
+      }),
+      // A quotation is a nested h-cite, which is enough on its own.
+      "quote without commentary": QuoteCard({
+        post: createPostView({ format: "quote", bodyHtml: undefined }),
+        mode: "feed",
+      }),
+    };
+
+    for (const [label, card] of Object.entries(cards)) {
+      const html = renderWithI18n(card);
+      expect(`${label}: ${html}`).not.toContain(
+        '<div class="e-content"></div>',
+      );
+    }
+  });
+
+  it("styles post titles by their own classes, never by their microformats class", () => {
+    const css = readComponentCss();
+
+    // `.p-name` is parsed API; styling it would silently retypeset any element
+    // that later needs the property — the quote attribution, for one.
+    expect(css).not.toMatch(/^\s*\.p-name\s*\{/m);
+    expect(css).toMatch(
+      /\.post-detail-title,\s*\.feed-compact-title\s*\{[^}]*font-family:\s*var\(--font-heading\);/,
+    );
+    // Compact note titles have no other class carrying the heading face.
+    const compactHtml = renderWithI18n(
+      NoteCard({ post: createPostView({ format: "note" }), mode: "compact" }),
+    );
+    expect(compactHtml).toContain("feed-compact-title");
+  });
+
+  it("keeps embedded quotes on the host panel's type scale", () => {
+    const css = readComponentCss();
+
+    // The quote body dropped `.e-content`, which is how this rule used to
+    // reach it; without the explicit class it would out-size the panel.
+    expect(css).toMatch(
+      /\.compose-reply-context-body\s*:is\(\s*\.prose,\s*\.e-content,\s*\.feed-quote,\s*\.feed-quote-content\s*\)\s*\{[^}]*font-size:\s*inherit;/,
+    );
+  });
+
   it("renders quote attachments in feed and detail modes", () => {
     const post = createPostView({ format: "quote" });
 
@@ -108,10 +379,7 @@ describe("timeline cards", () => {
       new URL("../../../styles/tokens.css", import.meta.url),
       "utf8",
     );
-    const css = readFileSync(
-      new URL("../../../styles/ui.css", import.meta.url),
-      "utf8",
-    );
+    const css = readComponentCss();
     const exportCss = readFileSync(
       new URL(
         "../../../services/export-theme/styles/main.css",
@@ -171,10 +439,7 @@ describe("timeline cards", () => {
       new URL("../../../preset.css", import.meta.url),
       "utf8",
     );
-    const uiCss = readFileSync(
-      new URL("../../../styles/ui.css", import.meta.url),
-      "utf8",
-    );
+    const uiCss = readComponentCss();
     const exportCss = readFileSync(
       new URL(
         "../../../services/export-theme/styles/main.css",
@@ -291,10 +556,7 @@ describe("timeline cards", () => {
       new URL("../../../preset.css", import.meta.url),
       "utf8",
     );
-    const uiCss = readFileSync(
-      new URL("../../../styles/ui.css", import.meta.url),
-      "utf8",
-    );
+    const uiCss = readComponentCss();
     const exportCss = readFileSync(
       new URL(
         "../../../services/export-theme/styles/main.css",
@@ -346,10 +608,7 @@ describe("timeline cards", () => {
   });
 
   it("keeps quote footers on the shared card spacing baseline", () => {
-    const css = readFileSync(
-      new URL("../../../styles/ui.css", import.meta.url),
-      "utf8",
-    );
+    const css = readComponentCss();
 
     expect(css).toContain(".feed-quote-post [data-post-meta] {");
     expect(css).not.toContain(
@@ -358,10 +617,7 @@ describe("timeline cards", () => {
   });
 
   it("uses inset-note styling for compose editor blockquotes", () => {
-    const css = readFileSync(
-      new URL("../../../styles/ui.css", import.meta.url),
-      "utf8",
-    );
+    const css = readComponentCss();
 
     expect(css).toMatch(
       /\.compose-tiptap-body\s+\.tiptap\s+blockquote\s*\{[\s\S]*background:\s*linear-gradient\(/,
@@ -378,10 +634,7 @@ describe("timeline cards", () => {
   });
 
   it("keeps quote compose aligned with quote-card typography", () => {
-    const css = readFileSync(
-      new URL("../../../styles/ui.css", import.meta.url),
-      "utf8",
-    );
+    const css = readComponentCss();
 
     expect(css).toMatch(
       /\.compose-quote-wrap\s*\{[\s\S]*background-color:\s*color-mix\(/,
@@ -393,10 +646,7 @@ describe("timeline cards", () => {
   });
 
   it("keeps reply context previews on thread-context type tokens", () => {
-    const uiCss = readFileSync(
-      new URL("../../../styles/ui.css", import.meta.url),
-      "utf8",
-    );
+    const uiCss = readComponentCss();
     const tokenCss = readFileSync(
       new URL("../../../styles/tokens.css", import.meta.url),
       "utf8",
@@ -416,10 +666,7 @@ describe("timeline cards", () => {
   });
 
   it("resets cloned reply previews away from feed/detail width constraints", () => {
-    const uiCss = readFileSync(
-      new URL("../../../styles/ui.css", import.meta.url),
-      "utf8",
-    );
+    const uiCss = readComponentCss();
     const unlayeredCssStart = uiCss.indexOf(" * Home description");
     const resetRule = uiCss.match(
       /\.compose-reply-context-body\s*:is\([^{}]*\[data-post-body\]\.prose[^{}]*\)\s*\{[^{}]*width:\s*100%;[^{}]*max-width:\s*none;[^{}]*\}/,
@@ -487,10 +734,7 @@ describe("timeline cards", () => {
   });
 
   it("keeps titled detail headers spaced as one reading group", () => {
-    const css = readFileSync(
-      new URL("../../../styles/ui.css", import.meta.url),
-      "utf8",
-    );
+    const css = readComponentCss();
 
     expect(css).toMatch(
       /\.post-header-block\s*\{[\s\S]*margin-bottom:\s*1\.7rem;/,
@@ -501,10 +745,7 @@ describe("timeline cards", () => {
   });
 
   it("keeps detail dates quiet while preserving standalone footer spacing", () => {
-    const css = readFileSync(
-      new URL("../../../styles/ui.css", import.meta.url),
-      "utf8",
-    );
+    const css = readComponentCss();
 
     expect(css).toMatch(
       /\.post-header-meta-link\s*\{[^}]*font-size:\s*var\(--type-ui-hint\);/,
@@ -518,13 +759,10 @@ describe("timeline cards", () => {
   });
 
   it("adds breathing room when a quote source leads directly into its footer", () => {
-    const css = readFileSync(
-      new URL("../../../styles/ui.css", import.meta.url),
-      "utf8",
-    );
+    const css = readComponentCss();
 
     expect(css).toMatch(
-      /\.feed-quote-attribution:has\(\+ \.post-menu-footer\)\s*\{[^}]*margin-bottom:\s*0\.45rem;/,
+      /\.feed-quote-cite:has\(\+ \.post-menu-footer\) \.feed-quote-attribution\s*\{[^}]*margin-bottom:\s*0\.45rem;/,
     );
   });
 
@@ -542,10 +780,7 @@ describe("timeline cards", () => {
   });
 
   it("progressively enhances canonical endnotes on wide detail and timeline posts", () => {
-    const css = readFileSync(
-      new URL("../../../styles/ui.css", import.meta.url),
-      "utf8",
-    );
+    const css = readComponentCss();
     const tokens = readFileSync(
       new URL("../../../styles/tokens.css", import.meta.url),
       "utf8",
@@ -764,4 +999,34 @@ describe("timeline cards", () => {
     expect(html).not.toContain("data-reply-trigger");
     expect(html).toContain("data-post-menu-trigger");
   });
+
+  it("ships every status badge to the author so the menu can reveal one", () => {
+    const html = renderWithI18n(
+      NoteCard({ post: createPostView({ format: "note" }), mode: "feed" }),
+    );
+
+    expect(html).toContain("post-status-pinned");
+    expect(html).toContain("post-status-private");
+    expect(html).toContain("post-status-draft");
+  });
+
+  it("gives a reader only the badges that apply", () => {
+    const plain = renderWithI18n(
+      NoteCard({ post: createPostView({ format: "note" }), mode: "feed" }),
+      false,
+    );
+    // Nothing to announce, so not even the wrapper.
+    expect(plain).not.toContain("post-status-badges");
+
+    const pinned = renderWithI18n(
+      NoteCard({
+        post: createPostView({ format: "note", pinned: true }),
+        mode: "feed",
+      }),
+      false,
+    );
+    expect(pinned).toContain("post-status-pinned");
+    expect(pinned).not.toContain("post-status-private");
+    expect(pinned).not.toContain("post-status-draft");
+  });
 });

package/src/ui/feed/thread-preview-state.ts

@@ -1,5 +1,19 @@
 import type { PostView } from "../../types.js";
+import { getThreadHiddenCount } from "../../lib/thread-fold.js";
 
+/**
+ * What the preview needs to know about its own fold.
+ *
+ * The count itself lives in `lib/thread-fold.ts`, where the feed reads it too —
+ * a card and a feed entry that disagreed about how many posts are hidden would
+ * be describing different threads.
+ *
+ * @param selection - The replies this preview shows, and the thread's total
+ * @returns The hidden-post count the gap link announces
+ * @example
+ * getThreadPreviewState({ leadingReplies, trailingReplies, latestReply,
+ *   totalReplyCount: 8 }); // { hiddenCount: 3 }
+ */
 export function getThreadPreviewState({
   leadingReplies,
   trailingReplies,
@@ -11,13 +25,13 @@ export function getThreadPreviewState({
   latestReply: PostView;
   totalReplyCount: number;
 }) {
-  const visibleReplyIds = new Set(
-    [...leadingReplies, ...trailingReplies, latestReply].map((post) => post.id),
-  );
-  const hiddenCount = Math.max(0, totalReplyCount - visibleReplyIds.size);
-
   return {
-    hiddenCount,
+    hiddenCount: getThreadHiddenCount({
+      leadingReplies,
+      trailingReplies,
+      latestReply,
+      totalReplyCount,
+    }),
   };
 }
 

package/src/ui/font-themes.ts

@@ -12,8 +12,7 @@
 import type { MessageDescriptor } from "@lingui/core";
 import {
   getCjkFontFromLanguageTag,
-  isCjkSerifFont,
-  type CjkSerifFont,
+  type CjkFontProfile,
 } from "../i18n/detect.js";
 
 /**
@@ -34,8 +33,6 @@ export interface FontTheme {
   description: MessageDescriptor;
 }
 
-const DEFAULT_CJK_SERIF_FALLBACK = '"Jant Language Fallback"';
-const DEFAULT_CJK_SANS_FALLBACK = '"Jant Language Fallback"';
 const HANS_CJK_SERIF_FALLBACK =
   '"Songti SC", STSong, SimSun, "Noto Serif SC", "Noto Serif CJK SC", "Songti TC", PMingLiU, MingLiU, "Noto Serif TC", "Noto Serif CJK TC"';
 const HANS_CJK_SANS_FALLBACK =
@@ -52,6 +49,20 @@ const KO_CJK_SERIF_FALLBACK =
   'Batang, "Noto Serif KR", "Noto Serif CJK KR", NanumMyeongjo';
 const KO_CJK_SANS_FALLBACK =
   '"Apple SD Gothic Neo", "Noto Sans KR", "Noto Sans CJK KR", "Malgun Gothic"';
+/*
+ * Default stacks for a page whose language names no CJK profile.
+ *
+ * A font stack cannot express "no opinion": every Latin family in a theme stack
+ * lacks Han coverage, and `ui-serif` / `serif` resolve to Times or New York,
+ * which lack it too — so a placeholder name leaves Chinese, Japanese and Korean
+ * text to the OS last-resort font (PingFang SC on Apple platforms), rendering a
+ * serif page in sans. The default therefore has to be real. Simplified comes
+ * first because it is the most common CJK content here; a page that knows its
+ * language gets the profile stacks above instead, which put the right glyph
+ * shapes first.
+ */
+const DEFAULT_CJK_SERIF_FALLBACK = `${HANS_CJK_SERIF_FALLBACK}, ${JP_CJK_SERIF_FALLBACK}, ${KO_CJK_SERIF_FALLBACK}`;
+const DEFAULT_CJK_SANS_FALLBACK = `${HANS_CJK_SANS_FALLBACK}, ${JP_CJK_SANS_FALLBACK}, ${KO_CJK_SANS_FALLBACK}`;
 const CJK_SERIF_FALLBACK_VAR = "var(--font-cjk-serif-fallback)";
 const CJK_SANS_FALLBACK_VAR = "var(--font-cjk-sans-fallback)";
 
@@ -117,46 +128,43 @@ export function getFontThemeCssVariables(
 }
 
 /**
- * Resolve the language font profile for the current content language.
+ * Resolve the CJK font profile for a content language.
  *
- * An adapted content language always wins. The explicit CJK setting is a
- * fallback for sites whose primary content language does not have a profile.
+ * Purely derived from the language — Simplified, Traditional, Japanese and
+ * Korean want different Han glyph shapes, and the language tag is the only
+ * thing that knows which. The page passes the language it is actually
+ * rendering: a post's own language on a post page, the view language on a
+ * language-filtered list, the site language otherwise.
  *
- * @param siteLanguage - BCP 47 content language tag
- * @param cjkFallback - Explicit CJK fallback setting
- * @returns Resolved CJK font profile, or `undefined` for the default stack
+ * @param language - BCP 47 content language tag
+ * @returns Resolved CJK font profile, or `undefined` to keep the token default
  * @example
- * resolveCjkFontProfile("zh-TW", "zh-Hans") // "zh-Hant"
+ * resolveCjkFontProfile("zh-TW") // "zh-Hant"
+ * resolveCjkFontProfile("en")    // undefined
  */
 export function resolveCjkFontProfile(
-  siteLanguage?: string,
-  cjkFallback?: string,
-): Exclude<CjkSerifFont, "off"> | undefined {
-  const contentProfile = siteLanguage
-    ? getCjkFontFromLanguageTag(siteLanguage)
-    : undefined;
-  if (contentProfile) return contentProfile;
-
-  return isCjkSerifFont(cjkFallback) && cjkFallback !== "off"
-    ? cjkFallback
-    : undefined;
+  language?: string,
+): CjkFontProfile | undefined {
+  return language ? getCjkFontFromLanguageTag(language) : undefined;
 }
 
 /**
  * Build serif and sans fallback variables for the resolved language profile.
  *
- * @param siteLanguage - BCP 47 content language tag
- * @param cjkFallback - Explicit CJK fallback setting
- * @returns CSS variables consumed by every font theme
+ * Empty for a language with no profile: `tokens.css` already carries a real
+ * script-neutral stack in both variables, so there is nothing to override.
+ *
+ * @param language - BCP 47 content language tag
+ * @returns CSS variables consumed by every font theme, empty when the token
+ *   defaults already apply
  * @example
- * getCjkFontCssVariables("en", "zh-Hans")
+ * getCjkFontCssVariables("zh-Hans")
  * // => { "--font-cjk-serif-fallback": '"Songti SC", ...', ... }
  */
 export function getCjkFontCssVariables(
-  siteLanguage?: string,
-  cjkFallback?: string,
+  language?: string,
 ): Record<string, string> {
-  switch (resolveCjkFontProfile(siteLanguage, cjkFallback)) {
+  switch (resolveCjkFontProfile(language)) {
     case "zh-Hans":
       return {
         "--font-cjk-serif-fallback": HANS_CJK_SERIF_FALLBACK,
@@ -182,7 +190,9 @@ export function getCjkFontCssVariables(
   }
 }
 
+/** The `--font-cjk-serif-fallback` value `tokens.css` ships as its default. */
 export const DEFAULT_FONT_CJK_SERIF_FALLBACK = DEFAULT_CJK_SERIF_FALLBACK;
+/** The `--font-cjk-sans-fallback` value `tokens.css` ships as its default. */
 export const DEFAULT_FONT_CJK_SANS_FALLBACK = DEFAULT_CJK_SANS_FALLBACK;
 
 export const BUILTIN_FONT_THEMES: FontTheme[] = [