@jant/core 0.6.15 → 0.7.0

package/src/db/schema.ts

@@ -15,26 +15,37 @@ import {
   check,
 } from "drizzle-orm/sqlite-core";
 import { sql } from "drizzle-orm";
-import { SYSTEM_NAV_KEY_VALUES } from "../types/constants.js";
-
-const SITE_STATUSES = ["active", "suspended"] as const;
-const SITE_DOMAIN_KINDS = ["primary", "alias"] as const;
-const SITE_MEMBER_ROLES = ["owner", "admin", "editor"] as const;
-const FORMATS = ["note", "link", "quote"] as const;
-const STATUSES = ["draft", "published"] as const;
-const VISIBILITIES = ["public", "latest_hidden", "private"] as const;
-const COLLECTION_SORT_ORDERS = ["newest", "oldest", "rating_desc"] as const;
-const NAV_ITEM_TYPES = ["link", "system", "collection", "page"] as const;
-const NAV_ITEM_PLACEMENTS = ["header", "more"] as const;
-const UPLOAD_SESSION_STATES = [
-  "pending",
-  "uploaded",
-  "completed",
-  "aborted",
-  "failed",
-] as const;
-const CONTENT_DISPOSITIONS = ["inline", "attachment"] as const;
+import {
+  ARCHIVE_LAYOUTS,
+  COLLECTION_DIRECTORY_ENTRY_TYPES,
+  COLLECTION_SORT_ORDERS,
+  CONTENT_DISPOSITIONS,
+  EARLIEST_FILTERABLE_YEAR,
+  FORMATS,
+  GITHUB_APP_ACCOUNT_TYPES,
+  LATEST_FILTERABLE_YEAR,
+  NAV_ITEM_PLACEMENTS,
+  NAV_ITEM_TYPES,
+  PATH_KINDS,
+  PUBLIC_ARCHIVE_VISIBILITIES,
+  SITE_DOMAIN_KINDS,
+  SITE_MEMBER_ROLES,
+  SITE_STATUSES,
+  SMART_COLLECTION_SORT_ORDERS,
+  STATUSES,
+  SYSTEM_NAV_KEY_VALUES,
+  UPLOAD_SESSION_STATES,
+  VISIBILITIES,
+} from "../types/constants.js";
 
+/**
+ * Render a value list as the `IN (...)` body of a CHECK constraint.
+ *
+ * Every list it is handed comes from `types/constants.ts`. Declaring one
+ * locally instead is how a CHECK once shipped missing an enum value: the
+ * shared list grew, the schema's private copy did not, and the generated
+ * constraint rejected rows the application treats as valid.
+ */
 function sqlTextEnum(values: readonly string[]) {
   return sql.raw(values.map((value) => `'${value}'`).join(", "));
 }
@@ -164,8 +175,46 @@ export const posts = sqliteTable(
     previewProvider: text("preview_provider"),
     replyToId: text("reply_to_id"),
     threadId: text("thread_id").notNull(),
+    /**
+     * BCP 47 content language in canonical form (`en`, `zh-Hans`).
+     *
+     * Uniform across a Thread: replies inherit the Root's value on creation and
+     * a language change rewrites every row in the Thread. Language filters can
+     * therefore be plain column predicates even on member-grained queries.
+     *
+     * NULL only exists before multilingual content is first enabled; enabling
+     * stamps every NULL row with the primary language.
+     */
+    language: text("language"),
+    /**
+     * Shared translation-group key (TypeID, `tgr_` prefix). Rows sharing a value
+     * are translations of one another — one row per language, no direction.
+     *
+     * Only ever set on Thread Roots (`thread_id = id`); enforced in the post
+     * service rather than by a table CHECK, because adding a CHECK to `post`
+     * would make drizzle-kit rebuild the table and silently drop the FTS
+     * triggers (`post_ai` / `post_ad` / `post_au`) that keep search current.
+     */
+    translationGroupId: text("translation_group_id"),
+    /**
+     * The author added this reply without announcing it. Persisted so both
+     * activity timestamps below stay recomputable from the rows alone.
+     * Always false on Thread roots.
+     */
+    quietReply: integer("quiet_reply", { mode: "boolean" })
+      .notNull()
+      .default(false),
     publishedAt: integer("published_at"),
+    /**
+     * Root only: newest published_at in the Thread, excluding quiet replies —
+     * "last announced". Drives Latest and the feeds.
+     */
     lastActivityAt: integer("last_activity_at"),
+    /**
+     * Root only: newest published_at in the Thread, quiet replies included —
+     * "last changed". Drives the archive's updated sort.
+     */
+    threadUpdatedAt: integer("thread_updated_at"),
     createdAt: integer("created_at").notNull(),
     updatedAt: integer("updated_at").notNull(),
   },
@@ -213,6 +262,9 @@ export const posts = sqliteTable(
     index("idx_post_site_root_published_activity")
       .on(table.siteId, table.lastActivityAt, table.id)
       .where(sql`${table.replyToId} IS NULL AND ${table.status} = 'published'`),
+    index("idx_post_site_root_thread_updated")
+      .on(table.siteId, table.threadUpdatedAt, table.id)
+      .where(sql`${table.replyToId} IS NULL AND ${table.status} = 'published'`),
     index("idx_post_site_root_draft_updated")
       .on(table.siteId, table.updatedAt, table.id)
       .where(sql`${table.replyToId} IS NULL AND ${table.status} = 'draft'`),
@@ -226,6 +278,12 @@ export const posts = sqliteTable(
       .where(
         sql`${table.status} = 'published' AND ${table.featuredAt} IS NOT NULL`,
       ),
+    // One Post per language inside a translation group. The `site_id` prefix
+    // matches the indexing convention here and lets the same index serve
+    // "list the members of this group" without a second index.
+    uniqueIndex("uq_post_site_translation_group_language")
+      .on(table.siteId, table.translationGroupId, table.language)
+      .where(sql`${table.translationGroupId} IS NOT NULL`),
   ],
 );
 
@@ -421,6 +479,108 @@ export const collections = sqliteTable(
   ],
 );
 
+// =============================================================================
+// Smart Collections
+// =============================================================================
+
+/**
+ * A collection whose members are decided by conditions rather than by tagging.
+ *
+ * Kept apart from `collection` rather than folded into it. The two share an
+ * identity shape — a path registry row, a title, a description — but half the
+ * columns of a merged table would be meaningless for half its rows, every query
+ * would branch, and a smart collection can filter *by* a collection, which in
+ * one table becomes a self-reference and a cycle to defend against. The
+ * resemblance belongs in a read model, not in the storage.
+ *
+ * The condition columns are declared once in `lib/filter-dimensions.ts`; this
+ * table is where they land. `NULL` always means "this dimension is not part of
+ * the conditions".
+ *
+ * Never private: `visibility` is constrained to the public archive values, so
+ * there is no such thing as a smart collection page that answers 404 to a
+ * reader. Per-post visibility still applies exactly as it does on a manual
+ * collection page.
+ *
+ * `collection_id` carries no foreign key, which makes it the one id column here
+ * that does not. None of the three actions is the right one: CASCADE would
+ * delete a smart collection — a page, with an address — because a collection it
+ * filters by went away, SET NULL would silently widen it from "Rust notes" to
+ * every post, and RESTRICT can only say `FOREIGN KEY constraint failed`, which
+ * no one should ever be shown. The refusal that belongs here is
+ * `smartCollections.assertCollectionUnused()`, which names the smart
+ * collections standing in the way; a constraint underneath it would add no
+ * answer, only turn every bulk delete into an ordering rule nothing enforces.
+ *
+ * What a dangling id costs is bounded: the condition compiles to an `IN` over a
+ * collection no `thread_collection` row carries, so the smart collection matches
+ * nothing. Visible and repairable by editing the conditions — not a page that
+ * quietly grew to the whole archive.
+ */
+export const smartCollections = sqliteTable(
+  "smart_collection",
+  {
+    id: text("id").primaryKey(),
+    siteId: text("site_id")
+      .notNull()
+      .references(() => sites.id, { onDelete: "cascade" }),
+    title: text("title").notNull(),
+    description: text("description"),
+
+    // --- Conditions (see lib/filter-dimensions.ts) --------------------------
+    format: text("format", { enum: FORMATS }),
+    year: integer("year"),
+    // No foreign key, alone among this schema's id columns — see the note under
+    // the table on why this one is held in the service instead.
+    collectionId: text("collection_id"),
+    /** `any` | `none` | comma-joined MEDIA_KINDS. One folded vocabulary. */
+    media: text("media"),
+    hasTitle: integer("has_title", { mode: "boolean" }),
+    hasReplies: integer("has_replies", { mode: "boolean" }),
+    visibility: text("visibility", { enum: PUBLIC_ARCHIVE_VISIBILITIES }),
+
+    // --- Presentation (not conditions) --------------------------------------
+    sort: text("sort", { enum: SMART_COLLECTION_SORT_ORDERS })
+      .notNull()
+      .default("newest"),
+    /** NULL follows the site's `ARCHIVE_DEFAULT_LAYOUT`. */
+    layout: text("layout", { enum: ARCHIVE_LAYOUTS }),
+
+    createdAt: integer("created_at").notNull(),
+    updatedAt: integer("updated_at").notNull(),
+  },
+  (table) => [
+    check(
+      "chk_smart_collection_format",
+      sql`${table.format} IS NULL OR ${table.format} IN (${sqlTextEnum(FORMATS)})`,
+    ),
+    check(
+      "chk_smart_collection_visibility",
+      sql`${table.visibility} IS NULL OR ${table.visibility} IN (${sqlTextEnum(PUBLIC_ARCHIVE_VISIBILITIES)})`,
+    ),
+    check(
+      "chk_smart_collection_sort",
+      sql`${table.sort} IN (${sqlTextEnum(SMART_COLLECTION_SORT_ORDERS)})`,
+    ),
+    check(
+      "chk_smart_collection_layout",
+      sql`${table.layout} IS NULL OR ${table.layout} IN (${sqlTextEnum(ARCHIVE_LAYOUTS)})`,
+    ),
+    check(
+      "chk_smart_collection_year",
+      sql`${table.year} IS NULL OR ${table.year} BETWEEN ${sql.raw(String(EARLIEST_FILTERABLE_YEAR))} AND ${sql.raw(String(LATEST_FILTERABLE_YEAR))}`,
+    ),
+    index("idx_smart_collection_site_created_at").on(
+      table.siteId,
+      table.createdAt,
+    ),
+    index("idx_smart_collection_site_collection_id").on(
+      table.siteId,
+      table.collectionId,
+    ),
+  ],
+);
+
 // =============================================================================
 // Path Registry (slug + alias + redirect)
 // =============================================================================
@@ -442,6 +602,10 @@ export const pathRegistry = sqliteTable(
     collectionId: text("collection_id").references(() => collections.id, {
       onDelete: "cascade",
     }),
+    smartCollectionId: text("smart_collection_id").references(
+      () => smartCollections.id,
+      { onDelete: "cascade" },
+    ),
     redirectToPath: text("redirect_to_path"),
     redirectType: integer("redirect_type"),
     archiveQuery: text("archive_query"),
@@ -451,7 +615,7 @@ export const pathRegistry = sqliteTable(
   (table) => [
     check(
       "chk_path_registry_kind",
-      sql`${table.kind} IN ('slug', 'alias', 'redirect', 'archive')`,
+      sql`${table.kind} IN (${sqlTextEnum(PATH_KINDS)})`,
     ),
     uniqueIndex("uq_path_registry_site_path").on(table.siteId, table.path),
     uniqueIndex("uq_path_registry_site_post_slug")
@@ -460,18 +624,28 @@ export const pathRegistry = sqliteTable(
     uniqueIndex("uq_path_registry_site_collection_slug")
       .on(table.siteId, table.collectionId)
       .where(sql`${table.kind} = 'slug' AND ${table.collectionId} IS NOT NULL`),
+    uniqueIndex("uq_path_registry_site_smart_collection_slug")
+      .on(table.siteId, table.smartCollectionId)
+      .where(
+        sql`${table.kind} = 'slug' AND ${table.smartCollectionId} IS NOT NULL`,
+      ),
     index("idx_path_registry_site_post_id").on(table.siteId, table.postId),
     index("idx_path_registry_site_collection_id").on(
       table.siteId,
       table.collectionId,
     ),
+    index("idx_path_registry_site_smart_collection_id").on(
+      table.siteId,
+      table.smartCollectionId,
+    ),
     check(
       "chk_path_registry_shape",
       sql`(
         ${table.kind} IN ('slug', 'alias')
         AND (
-          (${table.postId} IS NOT NULL AND ${table.collectionId} IS NULL)
-          OR (${table.postId} IS NULL AND ${table.collectionId} IS NOT NULL)
+          (${table.postId} IS NOT NULL AND ${table.collectionId} IS NULL AND ${table.smartCollectionId} IS NULL)
+          OR (${table.postId} IS NULL AND ${table.collectionId} IS NOT NULL AND ${table.smartCollectionId} IS NULL)
+          OR (${table.postId} IS NULL AND ${table.collectionId} IS NULL AND ${table.smartCollectionId} IS NOT NULL)
         )
         AND ${table.redirectToPath} IS NULL
         AND ${table.redirectType} IS NULL
@@ -480,6 +654,7 @@ export const pathRegistry = sqliteTable(
         ${table.kind} = 'redirect'
         AND ${table.postId} IS NULL
         AND ${table.collectionId} IS NULL
+        AND ${table.smartCollectionId} IS NULL
         AND ${table.redirectToPath} IS NOT NULL
         AND ${table.redirectType} IN (301, 302)
         AND ${table.archiveQuery} IS NULL
@@ -487,6 +662,7 @@ export const pathRegistry = sqliteTable(
         ${table.kind} = 'archive'
         AND ${table.postId} IS NULL
         AND ${table.collectionId} IS NULL
+        AND ${table.smartCollectionId} IS NULL
         AND ${table.redirectToPath} IS NULL
         AND ${table.redirectType} IS NULL
         AND ${table.archiveQuery} IS NOT NULL
@@ -506,10 +682,16 @@ export const collectionDirectoryItems = sqliteTable(
     siteId: text("site_id")
       .notNull()
       .references(() => sites.id, { onDelete: "cascade" }),
-    type: text("type", { enum: ["collection", "divider", "link"] }).notNull(),
+    type: text("type", {
+      enum: COLLECTION_DIRECTORY_ENTRY_TYPES,
+    }).notNull(),
     collectionId: text("collection_id").references(() => collections.id, {
       onDelete: "cascade",
     }),
+    smartCollectionId: text("smart_collection_id").references(
+      () => smartCollections.id,
+      { onDelete: "cascade" },
+    ),
     label: text("label"),
     url: text("url"),
     description: text("description"),
@@ -520,12 +702,16 @@ export const collectionDirectoryItems = sqliteTable(
   (table) => [
     check(
       "chk_collection_directory_item_type",
-      sql`${table.type} IN ('collection', 'divider', 'link')`,
+      sql`${table.type} IN (${sqlTextEnum(COLLECTION_DIRECTORY_ENTRY_TYPES)})`,
     ),
     index("idx_collection_directory_item_site_collection_id").on(
       table.siteId,
       table.collectionId,
     ),
+    index("idx_collection_directory_item_site_smart_collection_id").on(
+      table.siteId,
+      table.smartCollectionId,
+    ),
     uniqueIndex("uq_collection_directory_item_site_position").on(
       table.siteId,
       table.position,
@@ -535,27 +721,41 @@ export const collectionDirectoryItems = sqliteTable(
       .where(
         sql`${table.type} = 'collection' AND ${table.collectionId} IS NOT NULL`,
       ),
+    uniqueIndex("uq_collection_directory_item_site_smart_collection_once")
+      .on(table.siteId, table.smartCollectionId)
+      .where(
+        sql`${table.type} = 'smart_collection' AND ${table.smartCollectionId} IS NOT NULL`,
+      ),
     check(
       "chk_collection_directory_item_shape",
       sql`(
         ${table.type} = 'collection'
         AND ${table.collectionId} IS NOT NULL
+        AND ${table.smartCollectionId} IS NULL
+        AND ${table.label} IS NULL
+        AND ${table.url} IS NULL
+      ) OR (
+        ${table.type} = 'smart_collection'
+        AND ${table.collectionId} IS NULL
+        AND ${table.smartCollectionId} IS NOT NULL
         AND ${table.label} IS NULL
         AND ${table.url} IS NULL
       ) OR (
         ${table.type} = 'divider'
         AND ${table.collectionId} IS NULL
+        AND ${table.smartCollectionId} IS NULL
         AND ${table.url} IS NULL
       ) OR (
         ${table.type} = 'link'
         AND ${table.collectionId} IS NULL
+        AND ${table.smartCollectionId} IS NULL
         AND ${table.label} IS NOT NULL
         AND ${table.url} IS NOT NULL
       )`,
     ),
     check(
       "chk_collection_directory_item_label",
-      sql`${table.type} <> 'collection' OR ${table.label} IS NULL`,
+      sql`${table.type} NOT IN ('collection', 'smart_collection') OR ${table.label} IS NULL`,
     ),
     check(
       "chk_collection_directory_item_description",
@@ -621,6 +821,10 @@ export const navItems = sqliteTable(
     collectionId: text("collection_id").references(() => collections.id, {
       onDelete: "cascade",
     }),
+    smartCollectionId: text("smart_collection_id").references(
+      () => smartCollections.id,
+      { onDelete: "cascade" },
+    ),
     postId: text("post_id").references(() => posts.id, {
       onDelete: "cascade",
     }),
@@ -650,21 +854,31 @@ export const navItems = sqliteTable(
         ${table.type} = 'link'
         AND ${table.systemKey} IS NULL
         AND ${table.collectionId} IS NULL
+        AND ${table.smartCollectionId} IS NULL
         AND ${table.postId} IS NULL
       ) OR (
         ${table.type} = 'system'
         AND ${table.systemKey} IS NOT NULL
         AND ${table.collectionId} IS NULL
+        AND ${table.smartCollectionId} IS NULL
         AND ${table.postId} IS NULL
       ) OR (
         ${table.type} = 'collection'
         AND ${table.systemKey} IS NULL
         AND ${table.collectionId} IS NOT NULL
+        AND ${table.smartCollectionId} IS NULL
+        AND ${table.postId} IS NULL
+      ) OR (
+        ${table.type} = 'smart_collection'
+        AND ${table.systemKey} IS NULL
+        AND ${table.collectionId} IS NULL
+        AND ${table.smartCollectionId} IS NOT NULL
         AND ${table.postId} IS NULL
       ) OR (
         ${table.type} = 'page'
         AND ${table.systemKey} IS NULL
         AND ${table.collectionId} IS NULL
+        AND ${table.smartCollectionId} IS NULL
         AND ${table.postId} IS NOT NULL
       )`,
     ),
@@ -675,6 +889,9 @@ export const navItems = sqliteTable(
     uniqueIndex("uq_nav_item_site_collection_id")
       .on(table.siteId, table.collectionId)
       .where(sql`${table.collectionId} IS NOT NULL`),
+    uniqueIndex("uq_nav_item_site_smart_collection_id")
+      .on(table.siteId, table.smartCollectionId)
+      .where(sql`${table.smartCollectionId} IS NOT NULL`),
     uniqueIndex("uq_nav_item_site_post_id")
       .on(table.siteId, table.postId)
       .where(sql`${table.postId} IS NOT NULL`),
@@ -792,8 +1009,6 @@ export const verification = sqliteTable("verification", {
 // GitHub App Installations (junction table: installation ↔ site, many-to-many)
 // ---------------------------------------------------------------------------
 
-const GITHUB_APP_ACCOUNT_TYPES = ["User", "Organization"] as const;
-
 export const githubAppInstallation = sqliteTable(
   "github_app_installation",
   {

package/src/db/thread-activity.ts

@@ -0,0 +1,101 @@
+/**
+ * Thread activity — one definition, shared by every surface that orders by it.
+ *
+ * A Thread's activity is when it last **gained a post**. Editing an existing
+ * post is not activity: otherwise fixing a typo would drag a years-old thread
+ * back to the top of Latest and of every collection that holds it.
+ *
+ * This lived as three separate copies (the collection thread sort, the
+ * collection directory, and the Hugo export). One of them was changed in #144
+ * to treat a newer `updated_at` as activity and the others were not, so the
+ * same thread ranked differently depending on which page you were looking at,
+ * and the drift went unnoticed for months. Adding a fourth copy is the failure
+ * mode this module exists to prevent — call it instead.
+ *
+ * Two flavors of "last activity" exist, and they differ only in how they treat
+ * quiet replies:
+ *
+ * - `last_activity_at` — quiet replies excluded. "Last announced." Latest, the
+ *   feeds, and collection ordering read this.
+ * - `thread_updated_at` — quiet replies included. "Last changed." The
+ *   archive's updated sort reads this.
+ *
+ * Both are maintained on the Thread root by the post service; everything here
+ * only reads them, with fallbacks for rows that predate the columns.
+ */
+
+import { sql, type SQL, type SQLWrapper } from "drizzle-orm";
+
+/**
+ * Activity timestamp for a Thread root row, in SQL.
+ *
+ * Pass column references for a query whose rows are already Thread roots, or
+ * raw fragments (`sql.raw("root.last_activity_at")`) when reaching a root
+ * through a correlated subquery.
+ *
+ * **Correlated-subquery warning:** Drizzle only qualifies interpolated columns
+ * with their table name when the query has a join. In a single-table
+ * `select()`, `${posts.id}` renders as a bare `"id"`, which inside a subquery
+ * binds to the subquery's own alias instead of correlating to the outer row —
+ * silently, with no error. Write the outer table out (`"post"."id"`) in that
+ * case rather than interpolating.
+ *
+ * @param root - The root's three timestamp columns, most authoritative first
+ * @returns COALESCE expression usable in ORDER BY, GROUP BY, or a projection
+ *
+ * @example
+ * ```ts
+ * // Rows are already Thread roots (joined on thread_collection.thread_id):
+ * const activityAt = buildRootActivityExpr({
+ *   lastActivityAt: posts.lastActivityAt,
+ *   publishedAt: posts.publishedAt,
+ *   updatedAt: posts.updatedAt,
+ * });
+ * ```
+ */
+export function buildRootActivityExpr(root: {
+  lastActivityAt: SQLWrapper;
+  publishedAt: SQLWrapper;
+  updatedAt: SQLWrapper;
+}): SQL<number> {
+  return sql<number>`COALESCE(
+    ${root.lastActivityAt},
+    ${root.publishedAt},
+    ${root.updatedAt}
+  )`;
+}
+
+/** The Thread root's timestamp columns, named for a correlated subquery alias. */
+export function rootActivityColumns(alias: string): {
+  lastActivityAt: SQLWrapper;
+  publishedAt: SQLWrapper;
+  updatedAt: SQLWrapper;
+} {
+  return {
+    lastActivityAt: sql.raw(`${alias}.last_activity_at`),
+    publishedAt: sql.raw(`${alias}.published_at`),
+    updatedAt: sql.raw(`${alias}.updated_at`),
+  };
+}
+
+/**
+ * Activity timestamp for an already-loaded Thread root, in TypeScript.
+ *
+ * The same COALESCE order as {@link buildRootActivityExpr}, for callers that
+ * hold hydrated posts rather than a query builder.
+ *
+ * @param root - A Thread root post
+ * @returns Unix timestamp (seconds) of the root's last activity
+ *
+ * @example
+ * ```ts
+ * const activityAt = getRootActivityAt(threadRoot);
+ * ```
+ */
+export function getRootActivityAt(root: {
+  lastActivityAt?: number | null;
+  publishedAt?: number | null;
+  updatedAt: number;
+}): number {
+  return root.lastActivityAt ?? root.publishedAt ?? root.updatedAt;
+}

package/src/i18n/__tests__/detect.test.ts

@@ -1,5 +1,8 @@
 import { describe, it, expect } from "vitest";
-import { detectLocaleFromHeader, detectCjkFontFromHeader } from "../detect.js";
+import {
+  detectLocaleFromHeader,
+  getCjkFontFromLanguageTag,
+} from "../detect.js";
 
 describe("detectLocaleFromHeader", () => {
   it("returns en for en", () => {
@@ -45,94 +48,36 @@ describe("detectLocaleFromHeader", () => {
   });
 });
 
-describe("detectCjkFontFromHeader", () => {
-  // Simplified Chinese
-  it("maps zh-CN to zh-Hans", () => {
-    expect(detectCjkFontFromHeader("zh-CN")).toBe("zh-Hans");
+describe("getCjkFontFromLanguageTag", () => {
+  it("maps Simplified Chinese tags to the zh-Hans profile", () => {
+    expect(getCjkFontFromLanguageTag("zh-CN")).toBe("zh-Hans");
+    expect(getCjkFontFromLanguageTag("zh-SG")).toBe("zh-Hans");
+    expect(getCjkFontFromLanguageTag("zh-Hans")).toBe("zh-Hans");
+    // Bare `zh` is ambiguous in principle; Simplified is the majority reading.
+    expect(getCjkFontFromLanguageTag("zh")).toBe("zh-Hans");
   });
 
-  it("maps zh-SG to zh-Hans", () => {
-    expect(detectCjkFontFromHeader("zh-SG")).toBe("zh-Hans");
+  it("maps Traditional Chinese tags to the zh-Hant profile", () => {
+    expect(getCjkFontFromLanguageTag("zh-TW")).toBe("zh-Hant");
+    expect(getCjkFontFromLanguageTag("zh-HK")).toBe("zh-Hant");
+    expect(getCjkFontFromLanguageTag("zh-MO")).toBe("zh-Hant");
+    expect(getCjkFontFromLanguageTag("zh-Hant")).toBe("zh-Hant");
   });
 
-  it("maps zh-Hans to zh-Hans", () => {
-    expect(detectCjkFontFromHeader("zh-Hans")).toBe("zh-Hans");
-  });
-
-  it("maps bare zh to zh-Hans", () => {
-    expect(detectCjkFontFromHeader("zh")).toBe("zh-Hans");
-  });
-
-  // Traditional Chinese
-  it("maps zh-TW to zh-Hant", () => {
-    expect(detectCjkFontFromHeader("zh-TW")).toBe("zh-Hant");
-  });
-
-  it("maps zh-HK to zh-Hant", () => {
-    expect(detectCjkFontFromHeader("zh-HK")).toBe("zh-Hant");
-  });
-
-  it("maps zh-MO to zh-Hant", () => {
-    expect(detectCjkFontFromHeader("zh-MO")).toBe("zh-Hant");
-  });
-
-  it("maps zh-Hant to zh-Hant", () => {
-    expect(detectCjkFontFromHeader("zh-Hant")).toBe("zh-Hant");
-  });
-
-  // Japanese
-  it("maps ja to ja", () => {
-    expect(detectCjkFontFromHeader("ja")).toBe("ja");
-  });
-
-  it("maps ja-JP to ja", () => {
-    expect(detectCjkFontFromHeader("ja-JP")).toBe("ja");
-  });
-
-  // Korean
-  it("maps ko to ko", () => {
-    expect(detectCjkFontFromHeader("ko")).toBe("ko");
-  });
-
-  it("maps ko-KR to ko", () => {
-    expect(detectCjkFontFromHeader("ko-KR")).toBe("ko");
-  });
-
-  // q-value priority
-  it("picks highest q-value CJK language", () => {
-    expect(detectCjkFontFromHeader("fr;q=0.5,zh-CN;q=0.9,en;q=0.8")).toBe(
-      "zh-Hans",
-    );
-  });
-
-  it("picks first CJK when q-values are equal", () => {
-    expect(detectCjkFontFromHeader("zh-TW,en")).toBe("zh-Hant");
-  });
-
-  // Non-CJK fallback
-  it("returns off for non-CJK language", () => {
-    expect(detectCjkFontFromHeader("en-US")).toBe("off");
-  });
-
-  it("returns off for undefined", () => {
-    expect(detectCjkFontFromHeader(undefined)).toBe("off");
-  });
-
-  it("returns off for empty string", () => {
-    expect(detectCjkFontFromHeader("")).toBe("off");
-  });
-
-  it("skips entries with q=0", () => {
-    expect(detectCjkFontFromHeader("zh-CN;q=0,en")).toBe("off");
+  it("maps Japanese and Korean tags", () => {
+    expect(getCjkFontFromLanguageTag("ja")).toBe("ja");
+    expect(getCjkFontFromLanguageTag("ja-JP")).toBe("ja");
+    expect(getCjkFontFromLanguageTag("ko")).toBe("ko");
+    expect(getCjkFontFromLanguageTag("ko-KR")).toBe("ko");
   });
 
   it("is case-insensitive", () => {
-    expect(detectCjkFontFromHeader("ZH-CN")).toBe("zh-Hans");
+    expect(getCjkFontFromLanguageTag("ZH-CN")).toBe("zh-Hans");
   });
 
-  it("handles realistic browser header", () => {
-    expect(detectCjkFontFromHeader("zh-TW,zh;q=0.9,en-US;q=0.8,en;q=0.7")).toBe(
-      "zh-Hant",
-    );
+  it("returns nothing for languages with no CJK profile", () => {
+    expect(getCjkFontFromLanguageTag("en-US")).toBeUndefined();
+    expect(getCjkFontFromLanguageTag("")).toBeUndefined();
+    expect(getCjkFontFromLanguageTag("   ")).toBeUndefined();
   });
 });