@jant/core 0.6.16 → 0.7.1

package/src/lib/schemas.ts

@@ -10,11 +10,13 @@
 
 import { z } from "zod";
 import {
+  ARCHIVE_LAYOUTS,
   FORMATS,
   STATUSES,
   VISIBILITIES,
   SORT_ORDERS,
   COLLECTION_SORT_ORDERS,
+  SMART_COLLECTION_SORT_ORDERS,
   NAV_ITEM_TYPES,
   SYSTEM_NAV_KEY_VALUES,
   MAX_MEDIA_ATTACHMENTS,
@@ -30,14 +32,20 @@ import {
   type ConfigEditorDefinition,
   type ConfigKey,
 } from "../types.js";
-import { isCjkSerifFont } from "../i18n/detect.js";
 import {
+  formatLanguageList,
   isLocale,
   isValidContentLanguage,
   normalizeContentLanguage,
+  parseLanguageList,
 } from "../i18n/locales.js";
 import { ValidationError } from "./errors.js";
 import { createTypeIdSchema, ID_PREFIX } from "./ids.js";
+import {
+  FILTER_DIMENSION_KEYS,
+  FILTER_DIMENSIONS,
+  type PostFilterSelection,
+} from "./filter-dimensions.js";
 import { normalizeSlug } from "./slug-format.js";
 import { isReservedPath } from "./constants.js";
 import { sanitizeUrl, normalizePath } from "./url.js";
@@ -69,6 +77,27 @@ export function normalizeEmail(email: string): string {
   return email.trim().toLowerCase();
 }
 
+/**
+ * A display name to open an account under, before the author has given one.
+ *
+ * The first setup screen asks for credentials only, so better-auth needs a
+ * name it can create the row with; the second screen overwrites it with the
+ * site's name. This stands in only for the gap between the two, and for the
+ * setup that is abandoned in it — which is why it is the address the author
+ * just typed rather than a placeholder they would not recognise.
+ *
+ * @param email - The normalized address the account is being opened under
+ * @returns The part before the `@`, or the whole address when there is none
+ * @example
+ * ```ts
+ * deriveAccountName("owner@example.com");
+ * // Returns: "owner"
+ * ```
+ */
+export function deriveAccountName(email: string): string {
+  return email.split("@")[0]?.trim() || email;
+}
+
 /** Trim, strip control characters, and collapse to undefined when empty. */
 function sanitizeText(maxLength: number) {
   return z
@@ -166,13 +195,20 @@ export const NavItemTypeSchema = z.enum(NAV_ITEM_TYPES);
 export const SystemNavKeySchema = z.enum(SYSTEM_NAV_KEY_VALUES);
 
 /**
- * Redirect type enum schema
- * Form input validation for redirect type (stored as number in DB)
+ * Redirect type, as forms send it ("301") or as the API answers it (301).
+ * Parses to the string form; stored as a number.
  */
-export const RedirectTypeSchema = z.enum(["301", "302"]);
+export const RedirectTypeSchema = z.union([
+  z.enum(["301", "302"]),
+  z.literal(301).transform(() => "301" as const),
+  z.literal(302).transform(() => "302" as const),
+]);
 
 /**
- * Custom URL target type enum schema
+ * Custom URL target type enum schema.
+ *
+ * Every kind a stored path can be, including `archive` — which is read and
+ * listed but no longer created. See {@link CreatableCustomUrlTargetTypeSchema}.
  */
 export const CustomUrlTargetTypeSchema = z.enum([
   "post",
@@ -181,6 +217,20 @@ export const CustomUrlTargetTypeSchema = z.enum([
   "archive",
 ]);
 
+/**
+ * The target kinds a new custom URL may take.
+ *
+ * `archive` is absent: hand-typing `format=note&title=none` into a text field
+ * is the problem smart collections exist to replace, and a form that stopped
+ * offering it while the endpoint still accepted it would not have stopped
+ * offering it. Existing archive paths keep working indefinitely.
+ */
+export const CreatableCustomUrlTargetTypeSchema = z.enum([
+  "post",
+  "collection",
+  "redirect",
+]);
+
 /**
  * Rating schema (1-5 integer)
  */
@@ -193,9 +243,24 @@ export const RatingSchema = z.coerce
   .or(z.literal("").transform(() => undefined))
   .transform((v) => (v === 0 ? undefined : v));
 
+/**
+ * Any syntactically valid BCP 47 tag, normalized to canonical case.
+ *
+ * Deliberately open: Jant ships dashboard catalogs for a handful of locales but
+ * content can be written in any language.
+ */
+export const ContentLanguageSchema = z
+  .string()
+  .trim()
+  .refine(isValidContentLanguage, {
+    message: "Enter a valid BCP 47 language tag (e.g. en, zh-Hans, ja).",
+  })
+  .transform(normalizeContentLanguage);
+
 const PostIdSchema = createTypeIdSchema(ID_PREFIX.post);
 const MediaIdSchema = createTypeIdSchema(ID_PREFIX.media);
 const CollectionIdSchema = createTypeIdSchema(ID_PREFIX.collection);
+const SmartCollectionIdSchema = createTypeIdSchema(ID_PREFIX.smartCollection);
 const CollectionDirectoryItemIdSchema = createTypeIdSchema(
   ID_PREFIX.collectionDirectoryItem,
 );
@@ -294,6 +359,12 @@ const PostFieldsSchema = z.object({
     .optional(),
   replyToId: PostIdSchema.optional(),
   quietReply: z.boolean().optional(),
+  // Content language. The post service normalizes and enforces the
+  // thread-uniform rule; this only rejects tags that are not BCP 47 at all.
+  language: ContentLanguageSchema.optional().or(
+    z.literal("").transform(() => undefined),
+  ),
+  translationOfId: PostIdSchema.optional(),
   publishedAt: z.number().int().positive().optional(),
   mediaIds: z.array(MediaIdSchema).max(MAX_MEDIA_ATTACHMENTS).optional(),
   mediaAlts: z.record(MediaIdSchema, z.string()).optional(),
@@ -480,15 +551,32 @@ function refineSlugPathExclusivity<T extends { slug?: string; path?: string }>(
   });
 }
 
+/**
+ * Create only: a post's own record timestamps, in Unix seconds. An import or
+ * a migration restores them, so "last edited" (feed `<updated>`, sitemap
+ * `lastmod`) and Thread order (the root, then replies by creation time, then
+ * ID) survive the move.
+ * Omitted, both are the time of the request; `updatedAt` alone defaults to
+ * `createdAt`.
+ */
+const RestoredTimestampFields = {
+  createdAt: z.number().int().positive().optional(),
+  updatedAt: z.number().int().positive().optional(),
+};
+
 /**
  * API request body schema for creating a post
  */
 export const CreatePostSchema = refineSlugPathExclusivity(
-  refineCreatePostFormatShape(refineBodyExclusivity(PostFieldsSchema)),
+  refineCreatePostFormatShape(
+    refineBodyExclusivity(PostFieldsSchema.extend(RestoredTimestampFields)),
+  ),
 );
 
 export const CreatePostApiSchema = refineSlugPathExclusivity(
-  refineCreatePostFormatShape(refineBodyExclusivity(ApiPostFieldsSchema)),
+  refineCreatePostFormatShape(
+    refineBodyExclusivity(ApiPostFieldsSchema.extend(RestoredTimestampFields)),
+  ),
 );
 
 /**
@@ -566,6 +654,14 @@ export const CreateNavItemSchema = z.discriminatedUnion("type", [
     label: sanitizeText(100).pipe(z.string().min(1)).optional(),
     placement: z.enum(["header", "more"]).optional(),
   }),
+  // Placed exactly like a collection — the label follows the target's title
+  // and the URL follows its address; only which column holds the key differs.
+  z.object({
+    type: z.literal("smart_collection"),
+    smartCollectionId: SmartCollectionIdSchema,
+    label: sanitizeText(100).pipe(z.string().min(1)).optional(),
+    placement: z.enum(["header", "more"]).optional(),
+  }),
   z.object({
     type: z.literal("page"),
     postId: PostIdSchema,
@@ -620,6 +716,19 @@ export const CreateCollectionDirectoryItemSchema = z.discriminatedUnion(
   ],
 );
 
+/**
+ * A row in the collections directory, as the drag surface names it.
+ *
+ * A placed row is named by its directory row id. A collection or smart
+ * collection that has never been placed is named by its own id, because that is
+ * all the directory has to render — moving one is what gives it a row.
+ */
+export const CollectionDirectoryRowIdSchema = z.union([
+  CollectionDirectoryItemIdSchema,
+  CollectionIdSchema,
+  SmartCollectionIdSchema,
+]);
+
 export const UpdateCollectionDirectoryItemSchema = z.object({
   label: z.union([CollectionDirectoryLabelSchema, z.null()]).optional(),
   url: CollectionDirectoryLinkUrlSchema.optional(),
@@ -633,6 +742,7 @@ export {
   NavItemIdSchema,
   PathIdSchema,
   PostIdSchema,
+  SmartCollectionIdSchema,
 };
 
 /**
@@ -677,6 +787,61 @@ export const CreateCollectionSchema = z.object({
  */
 export const UpdateCollectionSchema = CreateCollectionSchema.partial();
 
+/**
+ * What a stored selection may hold — the validator a create or update request
+ * runs its conditions through.
+ *
+ * Assembled from the dimension registry rather than restated, so a new
+ * dimension is accepted by every endpoint the moment it is declared, and a
+ * dimension whose stored vocabulary is narrower than its URL one (`visibility`)
+ * is narrow everywhere at once.
+ *
+ * The registry itself carries plain predicates, not schemas, because the smart
+ * collection dialog compiles it into the browser bundle. The Zod wrapper lives
+ * here, on the server side of that line, where request bodies are validated and
+ * a rejected condition still has to say which one it was.
+ */
+export const PostFilterSelectionSchema = z
+  .object(
+    Object.fromEntries(
+      FILTER_DIMENSION_KEYS.map((key) => [
+        key,
+        z
+          .custom((value) => FILTER_DIMENSIONS[key].storage.isStorable(value), {
+            message: `Invalid value for the ${key} condition`,
+          })
+          .optional(),
+      ]),
+    ),
+  )
+  .strict() as unknown as z.ZodType<PostFilterSelection>;
+
+/**
+ * API request body schema for creating a smart collection.
+ *
+ * The conditions come from the dimension registry rather than being restated
+ * here, so a new dimension is accepted the moment it is declared and a stored
+ * vocabulary narrower than the URL one (`visibility` never being `private`)
+ * is narrow at every entry point at once.
+ */
+export const CreateSmartCollectionSchema = z.object({
+  slug: CollectionSlugSchema,
+  title: CollectionTitleSchema,
+  description: CollectionDescriptionValueSchema.nullable().optional(),
+  // Omitted means no conditions, which is the honest spelling of "every post".
+  selection: PostFilterSelectionSchema.optional(),
+  sort: z.enum(SMART_COLLECTION_SORT_ORDERS).optional(),
+  layout: z.enum(ARCHIVE_LAYOUTS).nullable().optional(),
+});
+
+export const UpdateSmartCollectionSchema =
+  CreateSmartCollectionSchema.partial();
+
+/** The body of a preview request: the conditions, and nothing else. */
+export const SmartCollectionPreviewSchema = z.object({
+  selection: PostFilterSelectionSchema.optional(),
+});
+
 export const SiteNameSettingSchema = sanitizeSettingText(MAX_SITE_NAME_LENGTH);
 export const SiteDescriptionSettingSchema = sanitizeSettingText(
   MAX_SITE_DESCRIPTION_LENGTH,
@@ -808,11 +973,16 @@ export function normalizeEditableSettingValue(
         );
       }
       break;
-    case "CJK_SERIF_FONT":
-      if (!isCjkSerifFont(normalized)) {
-        throw new ValidationError("Choose an available CJK font fallback.");
+    case "MULTILINGUAL_ENABLED":
+      if (normalized !== "true" && normalized !== "false") {
+        throw new ValidationError("Multilingual content is on or off.");
       }
       break;
+    case "ADDITIONAL_LANGUAGES":
+      // Re-serialized from the parsed form so a hand-written value cannot
+      // store blanks, duplicates, or non-canonical casing.
+      normalized = formatLanguageList(parseLanguageList(normalized));
+      break;
     case "TIME_ZONE":
       if (!isSupportedTimeZone(normalized)) {
         throw new ValidationError("Choose a valid time zone.");
@@ -837,11 +1007,10 @@ export const CreateCustomUrlSchema = z.object({
       "Path must contain only lowercase alphanumeric characters, hyphens, slashes, and dots",
     )
     .transform((p) => (p.startsWith("/") ? p : `/${p}`)),
-  targetType: CustomUrlTargetTypeSchema,
+  targetType: CreatableCustomUrlTargetTypeSchema,
   targetId: z.string().optional(),
   toPath: z.string().optional(),
   redirectType: RedirectTypeSchema.optional(),
-  archiveQuery: z.string().optional(),
 });
 
 // =============================================================================
@@ -849,10 +1018,13 @@ export const CreateCustomUrlSchema = z.object({
 // =============================================================================
 
 /**
- * Setup form validation schema
+ * The first of the two screens a self-hosted site is set up through.
+ *
+ * Credentials and nothing else. Everything about the site itself waits for the
+ * second screen, which is the same screen a hosted site shows — so the two
+ * install kinds converge instead of keeping two forms that drift.
  */
-export const SetupSchema = z.object({
-  siteName: z.string().min(1, "Site name is required"),
+export const SetupAccountSchema = z.object({
   email: z
     .string()
     .transform(normalizeEmail)
@@ -863,6 +1035,70 @@ export const SetupSchema = z.object({
     .max(128),
 });
 
+/**
+ * Setup on a site whose shell already exists and is already named.
+ *
+ * A control plane created the site and its owner, so the only thing left to
+ * settle is the language its author writes in — the one fact no header, host,
+ * or billing record can supply.
+ */
+export const SetupLanguageSchema = z.object({
+  contentLanguage: ContentLanguageSchema,
+  /**
+   * The Jant Discover answer, from the checkbox on the setup screen.
+   *
+   * Optional, and absence is not `false`: an older client or a scripted setup
+   * sends nothing, and that has to keep meaning "leave the deployment default
+   * in force" rather than "the author said no".
+   */
+  discover: z.boolean().optional(),
+});
+
+/**
+ * The second of the two self-hosted screens: the same questions the hosted
+ * screen asks, plus the name only a self-hosted site is still missing.
+ *
+ * Which of the two applies is not a property of the form but of the site — a
+ * site that already has a name is never asked for one — so the route picks the
+ * schema by reading the stored name rather than trusting a field.
+ */
+export const SetupSiteSchema = SetupLanguageSchema.extend({
+  // The message is set twice over on purpose: `.min(1)` catches a field left
+  // blank, and the type-level `error` catches a form that carried no field at
+  // all. Without the second, a scripted setup is told "expected string,
+  // received undefined" — which names nothing the author can act on.
+  siteName: z
+    .string({ error: "Site name is required" })
+    .min(1, "Site name is required"),
+});
+
+/** The answers the last setup screen collects from either install kind. */
+export type SetupLanguageAnswers = z.infer<typeof SetupLanguageSchema>;
+
+/**
+ * Both setup screens' answers at once, for `jant setup`: a self-hosted install
+ * set up by its deployment rather than in a browser.
+ *
+ * Only the credentials are required. Everything the second screen asks has
+ * the default an empty answer gets there, and a browser's guesses — its
+ * language, its time zone — have no counterpart here.
+ */
+export const InstanceSetupSchema = SetupAccountSchema.extend({
+  siteId: createTypeIdSchema(ID_PREFIX.site).optional(),
+  siteName: z
+    .string()
+    .trim()
+    .min(1, "Site name cannot be empty")
+    .max(MAX_SITE_NAME_LENGTH)
+    .optional(),
+  siteLanguage: ContentLanguageSchema.optional(),
+  timeZone: z
+    .string()
+    .refine(isSupportedTimeZone, "Choose a valid time zone.")
+    .transform(normalizeTimeZone)
+    .optional(),
+});
+
 /**
  * Sign-in form validation schema
  */

package/src/lib/site-header-fragment.tsx

@@ -29,7 +29,8 @@ export async function renderSiteHeaderHtml(c: Context<Env>): Promise<string> {
         links={navData.links}
         currentPath={navData.currentPath}
         sitePathPrefix={navData.sitePathPrefix}
-        siteAvatarUrl={navData.siteAvatarUrl}
+        basePath={navData.basePath}
+        siteAvatarThumbUrl={navData.siteAvatarThumbUrl}
         showHeaderAvatar={navData.showHeaderAvatar}
       />
     </I18nProvider>,

package/src/lib/site-unavailable-page.ts

@@ -0,0 +1,47 @@
+/**
+ * Standalone page served when a site resolves but is suspended.
+ *
+ * Kept deliberately self-contained (no theme, no site services, no i18n
+ * catalog): it renders before any site context exists, and the site whose
+ * theme we would otherwise use is exactly the one that is unavailable.
+ *
+ * The copy stays provider-neutral. Hosted deployments pass their brand across
+ * the boundary through `HOSTED_CONTROL_PLANE_PROVIDER_NAME` /
+ * `HOSTED_CONTROL_PLANE_BASE_URL`, which turn the last line into a real link
+ * back to the control plane; a self-hosted instance renders the same page
+ * without one.
+ */
+
+import { getHostedControlPlaneProviderLabel } from "./env.js";
+import { getHostedControlPlaneDashboardUrl } from "./hosted-signin.js";
+import { escapeHtml } from "./html.js";
+
+export function renderSiteUnavailablePage(
+  env: object | undefined | null,
+): string {
+  const providerLabel = getHostedControlPlaneProviderLabel(env);
+  const dashboardUrl = getHostedControlPlaneDashboardUrl(env);
+
+  const ownerLine =
+    dashboardUrl && providerLabel
+      ? `<p>If it's your site, sign in to <a href="${escapeHtml(dashboardUrl)}">${escapeHtml(providerLabel)}</a> to bring it back online.</p>`
+      : `<p>If it's your site, sign in to your hosting provider to bring it back online.</p>`;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>This site is offline</title>
+<style>body{font-family:system-ui,sans-serif;display:flex;justify-content:center;align-items:center;min-height:100vh;margin:0;background:#fafafa;color:#111;padding:24px}div{max-width:460px;text-align:left}h1{font-size:1.25rem;font-weight:600;margin:0 0 12px}p{color:#4a4a4a;line-height:1.6;margin:12px 0}a{color:#0f766e}@media(prefers-color-scheme:dark){body{background:#111;color:#fafafa}p{color:#a1a1a1}a{color:#2dd4bf}}</style>
+</head>
+<body>
+<div>
+<h1>This site is offline</h1>
+<p>There's nothing to read here right now &mdash; the site's hosting has stopped.</p>
+${ownerLine}
+</div>
+</body>
+</html>`;
+}

package/src/lib/slug.ts

@@ -5,7 +5,7 @@
  * Handles three cases: user-provided slug, title-based slug, and random-only slug.
  */
 
-import { slugify } from "./url.js";
+import { slugify } from "./slugify.js";
 import { generateRandomId } from "./nanoid.js";
 import { isReservedPath } from "./constants.js";
 import { ValidationError, ConflictError } from "./errors.js";
@@ -19,6 +19,21 @@ export interface SlugOptions {
   title?: string;
   /** Length of random IDs */
   idLength: number;
+  /**
+   * URL form of the post's language (lowercased BCP 47 tag, e.g. `zh-hant`),
+   * set only for posts written in a non-primary language. Used as the first
+   * fallback when a title-based slug collides, so the transliterations of a
+   * translated pair land on `shu-ping` and `shu-ping-en` rather than a random
+   * suffix. Omitted for primary-language posts: the bare namespace belongs to
+   * them, and a language suffix among same-language posts distinguishes nothing.
+   */
+  languageSuffix?: string;
+  /**
+   * URL prefixes currently served by language views. A slug matching one would
+   * be shadowed by that view and never resolve, so it is treated as reserved
+   * for as long as the language is configured.
+   */
+  reservedPrefixes?: readonly string[];
   /** Callback to check if a slug is available (checks post slugs + path_registry paths) */
   isAvailable: (slug: string) => Promise<boolean>;
 }
@@ -28,7 +43,7 @@ export interface SlugOptions {
  *
  * Resolution order:
  * 1. User-provided slug → validate format, check reserved, check availability
- * 2. Title exists → slugify(title), append -{randomId} if conflict
+ * 2. Title exists → slugify(title), then -{languageSuffix}, then -{randomId}
  * 3. No title → pure random ID
  *
  * @param opts - Slug generation options
@@ -42,16 +57,33 @@ export interface SlugOptions {
  * // Title-based
  * await generatePostSlug({ title: "Hello World", idLength: 5, isAvailable: check });
  *
+ * // Title-based in a secondary language, colliding with an existing slug
+ * await generatePostSlug({
+ *   title: "書評",
+ *   languageSuffix: "en",
+ *   idLength: 5,
+ *   isAvailable: check,
+ * }); // => "shu-ping-en"
+ *
  * // Random
  * await generatePostSlug({ idLength: 5, isAvailable: check });
  * ```
  */
 export async function generatePostSlug(opts: SlugOptions): Promise<string> {
-  const { slug, title, idLength, isAvailable } = opts;
+  const {
+    slug,
+    title,
+    idLength,
+    languageSuffix,
+    reservedPrefixes = [],
+    isAvailable,
+  } = opts;
+  const isReserved = (candidate: string) =>
+    isReservedPath(candidate, reservedPrefixes);
 
   // Case 1: User-provided slug
   if (slug) {
-    if (isReservedPath(slug)) {
+    if (isReserved(slug)) {
       throw new ValidationError(
         `Slug "${slug}" is reserved and cannot be used`,
       );
@@ -66,15 +98,27 @@ export async function generatePostSlug(opts: SlugOptions): Promise<string> {
   // Case 2: Title-based slug
   if (title) {
     const base = slugify(title);
-    if (base && !isReservedPath(base)) {
+    if (base && !isReserved(base)) {
       const available = await isAvailable(base);
       if (available) return base;
+
+      // A readable language suffix beats a random one, and it is exactly the
+      // collision a translated pair produces.
+      if (languageSuffix) {
+        const languageCandidate = `${base}-${languageSuffix}`;
+        if (
+          !isReserved(languageCandidate) &&
+          (await isAvailable(languageCandidate))
+        ) {
+          return languageCandidate;
+        }
+      }
     }
 
     // Append random suffix on conflict or reserved base
     for (let i = 0; i < MAX_RETRIES; i++) {
       const candidate = `${base || generateRandomId(idLength)}-${generateRandomId(idLength)}`;
-      if (!isReservedPath(candidate) && (await isAvailable(candidate))) {
+      if (!isReserved(candidate) && (await isAvailable(candidate))) {
         return candidate;
       }
     }
@@ -86,7 +130,7 @@ export async function generatePostSlug(opts: SlugOptions): Promise<string> {
   // Case 3: Pure random
   for (let i = 0; i < MAX_RETRIES; i++) {
     const candidate = generateRandomId(idLength);
-    if (!isReservedPath(candidate) && (await isAvailable(candidate))) {
+    if (!isReserved(candidate) && (await isAvailable(candidate))) {
       return candidate;
     }
   }

package/src/lib/slugify.ts

@@ -0,0 +1,113 @@
+/**
+ * Slug generation from free text.
+ *
+ * Lives apart from `url.ts` on purpose: `limax` drags the whole `pinyin-pro`
+ * dictionary (≈390 KB minified) into any bundle that imports it. Keeping the
+ * dictionary behind this single module lets the browser load it lazily via
+ * `client/lazy-slugify.ts`, while `url.ts` stays cheap enough for the public
+ * bundle. The build guard in `vite.shared.ts` fails the client build if
+ * `pinyin-pro` ever lands in an entry chunk again.
+ */
+
+import limax from "limax";
+
+import {
+  HAN_RE,
+  HANGUL_RE,
+  KANA_RE,
+  hangulToLatin,
+  kanaToRomaji,
+} from "./translit.js";
+
+const HAN_GLOBAL_RE = /\p{Script=Han}/gu;
+const CONTENT_CHAR_RE = /[\p{L}\p{N}]/u;
+const ASCII_ALNUM_RE = /[a-zA-Z0-9]/;
+
+/**
+ * Minimum fraction of a title's letters/digits the transliteration pipeline
+ * must handle for the result to be usable. Below this, too much meaning is
+ * lost (e.g. mixed kanji+kana Japanese where the semantic core is kanji, or
+ * scripts limax drops entirely) and `slugify` returns "" so callers fall back
+ * to their random-ID path instead of shipping a garbled slug.
+ */
+const SLUG_COVERAGE_THRESHOLD = 0.75;
+
+/** Per-character limax probe cache: does this char transliterate to anything? */
+const charCoverageCache = new Map<string, boolean>();
+
+function isCharCovered(char: string): boolean {
+  if (ASCII_ALNUM_RE.test(char)) return true;
+  let covered = charCoverageCache.get(char);
+  if (covered === undefined) {
+    covered = limax(char, { tone: false }).length > 0;
+    charCoverageCache.set(char, covered);
+  }
+  return covered;
+}
+
+function slugCoverage(text: string, japanese: boolean): number {
+  let content = 0;
+  let covered = 0;
+  for (const char of text) {
+    if (!CONTENT_CHAR_RE.test(char)) continue;
+    content++;
+    if (KANA_RE.test(char) || HANGUL_RE.test(char)) {
+      covered++;
+    } else if (japanese && HAN_RE.test(char)) {
+      // Kanji in a kana-containing title is dropped, never pinyin-read.
+    } else if (isCharCovered(char)) {
+      covered++;
+    }
+  }
+  return content === 0 ? 0 : covered / content;
+}
+
+/**
+ * Converts text to a URL-friendly slug.
+ *
+ * Transliterates i18n text to Latin before slugifying: Korean hangul via
+ * Revised Romanization, Japanese kana via Hepburn romaji (both in-house, see
+ * `translit.ts`), everything else (Han → pinyin, Cyrillic, accents, …) via
+ * limax. When the title contains kana it is treated as Japanese and Han
+ * characters are dropped rather than misread as Chinese pinyin; Han without
+ * kana is treated as Chinese.
+ *
+ * Returns `""` when transliteration would lose too much of the title (see
+ * `SLUG_COVERAGE_THRESHOLD`) — every caller treats an empty base as "no
+ * usable title" and falls back to a random ID, which beats publishing a
+ * garbled slug.
+ *
+ * @param text - The text to convert to a slug
+ * @returns The slugified string, or `""` when no usable slug can be derived
+ *
+ * @example
+ * ```ts
+ * slugify("Hello World! This is a Test.");
+ * // Returns: "hello-world-this-is-a-test"
+ *
+ * slugify("书评");
+ * // Returns: "shu-ping"
+ *
+ * slugify("안녕하세요 세계");
+ * // Returns: "annyeonghaseyo-segye"
+ *
+ * slugify("ハンバーガー");
+ * // Returns: "hanbaga"
+ *
+ * slugify("日本語のタイトルです");
+ * // Returns: "" (kanji carries the meaning and can't be transliterated)
+ * ```
+ */
+export function slugify(text: string): string {
+  const japanese = KANA_RE.test(text);
+  let pre = text;
+  if (japanese) {
+    pre = kanaToRomaji(pre.replace(HAN_GLOBAL_RE, " "));
+  }
+  if (HANGUL_RE.test(pre)) {
+    pre = hangulToLatin(pre);
+  }
+  const base = limax(pre, { tone: false }).replace(/_/g, "-");
+  if (!base) return "";
+  return slugCoverage(text, japanese) >= SLUG_COVERAGE_THRESHOLD ? base : "";
+}