@jant/core 0.6.16 → 0.7.0

package/src/lib/github-sync-site-config.ts

@@ -29,10 +29,13 @@ export async function buildSyncSiteConfig(c: {
     siteUrl: appConfig.siteUrl,
     siteDescription: appConfig.siteDescription,
     siteLanguage: appConfig.siteLanguage,
+    multilingualEnabled: appConfig.multilingualEnabled,
+    additionalLanguages: appConfig.additionalLanguages,
     showJantBrandingOnHome: appConfig.showJantBrandingOnHome,
     publicApiEnabled: appConfig.publicApiEnabled,
     rssFeedsEnabled: appConfig.rssFeedsEnabled,
     mainRssFeed: appConfig.mainRssFeed,
+    archiveDefaultLayout: appConfig.archiveDefaultLayout,
     siteFooter: appConfig.siteFooter,
     showHeaderAvatar: appConfig.showHeaderAvatar,
     siteAvatarUrl: appConfig.siteAvatarUrl,

package/src/lib/hosted-signin.ts

@@ -60,7 +60,7 @@ export function getHostedControlPlaneResetUrl(
 export function getHostedControlPlaneDashboardUrl(
   env: object | undefined | null,
 ): string | null {
-  return buildHostedControlPlaneUrl(env, "/sites");
+  return buildHostedControlPlaneUrl(env, "/app");
 }
 
 export function getHostedControlPlaneAccountUrl(

package/src/lib/http-cache.ts

@@ -0,0 +1,148 @@
+/**
+ * Conditional-request helpers.
+ *
+ * Transport-level only: deriving an entity tag for a response body, and
+ * deciding whether the request already holds it. Nothing here knows what the
+ * body represents.
+ */
+
+const textEncoder = new TextEncoder();
+
+/**
+ * One entity tag inside an `If-None-Match` list, weak prefix included.
+ *
+ * Matching quoted runs rather than splitting on commas is deliberate: RFC 9110
+ * allows a comma inside an entity tag's opaque part, so a naive split can tear
+ * one tag into two that match nothing.
+ */
+const ENTITY_TAG = /(?:W\/)?"[^"]*"/g;
+
+/** Drop the weak prefix, which the weak comparison in RFC 9110 ignores. */
+function opaqueTag(tag: string): string {
+  return tag.startsWith("W/") ? tag.slice(2) : tag;
+}
+
+/**
+ * Derive a strong entity tag from a response body.
+ *
+ * The tag is a truncated SHA-256 of the exact bytes that would be sent, so
+ * two equal tags do mean two identical responses — which is what makes the
+ * tag strong rather than `W/`-weak. 128 bits is far past the point where a
+ * collision could plausibly pin a stale body in a cache.
+ *
+ * @param body - Serialized response body
+ * @returns Quoted entity tag, ready for an `ETag` header
+ * @example
+ * ```ts
+ * const etag = await strongETag(xml); // '"9f86d081884c7d65..."'
+ * ```
+ */
+export async function strongETag(body: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    textEncoder.encode(body),
+  );
+
+  let hex = "";
+  for (const byte of new Uint8Array(digest, 0, 16)) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+
+  return `"${hex}"`;
+}
+
+/**
+ * Whether a request's `If-None-Match` already holds `etag`.
+ *
+ * Comparison is the weak one RFC 9110 requires for `If-None-Match`: the weak
+ * prefix is ignored on both sides, and any tag in the list can match. `*`
+ * matches whenever the resource exists, which it does by the time a response
+ * body has been rendered.
+ *
+ * @param header - Raw `If-None-Match` header value, absent when not sent
+ * @param etag - Entity tag of the response about to be sent
+ * @returns `true` when the response can be answered with `304`
+ * @example
+ * ```ts
+ * matchesIfNoneMatch('W/"abc", "def"', '"def"'); // true
+ * ```
+ */
+export function matchesIfNoneMatch(
+  header: string | null | undefined,
+  etag: string,
+): boolean {
+  if (!header) return false;
+  if (header.trim() === "*") return true;
+
+  const target = opaqueTag(etag);
+  for (const candidate of header.match(ENTITY_TAG) ?? []) {
+    if (opaqueTag(candidate) === target) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Headers a `304` carries over from the response it stands in for.
+ *
+ * RFC 9110 asks for the fields a cache would otherwise have to invent or
+ * discard: the validator itself, the freshness the entry is stored under, and
+ * the identity of what was validated.
+ */
+const NOT_MODIFIED_HEADERS = [
+  "Cache-Control",
+  "Content-Location",
+  "Date",
+  "ETag",
+  "Expires",
+  "Vary",
+] as const;
+
+/**
+ * Answer a conditional request with `304` when the response is one the client
+ * already holds.
+ *
+ * This is the only place in the app that turns a validator into a `304`, and
+ * it runs at the outer edge of the request — outside the Worker response
+ * cache. Both halves of that matter: a cache hit is revalidated without
+ * reaching a route, and a cache miss still renders and stores the whole
+ * document before the body is dropped, so the next reader gets a cache entry
+ * rather than a `304` that cannot be stored.
+ *
+ * Anything without an entity tag passes through untouched, so a route opts in
+ * simply by emitting one.
+ *
+ * @param request - Incoming request, read for `If-None-Match`
+ * @param response - Response the app produced
+ * @returns A bare `304`, or the response unchanged
+ * @example
+ * ```ts
+ * return withConditionalResponse(request, await handle(request));
+ * ```
+ */
+export function withConditionalResponse(
+  request: Request,
+  response: Response,
+): Response {
+  if (request.method !== "GET" && request.method !== "HEAD") return response;
+  if (response.status !== 200) return response;
+
+  // A 304 drops the body, and with it any header that only makes sense
+  // attached to one. A response setting a cookie is left alone rather than
+  // stripped down to a validator.
+  if (response.headers.has("Set-Cookie")) return response;
+
+  const etag = response.headers.get("ETag");
+  if (!etag) return response;
+  if (!matchesIfNoneMatch(request.headers.get("If-None-Match"), etag)) {
+    return response;
+  }
+
+  const headers = new Headers();
+  for (const name of NOT_MODIFIED_HEADERS) {
+    const value = response.headers.get(name);
+    if (value !== null) headers.set(name, value);
+  }
+
+  return new Response(null, { status: 304, headers });
+}

package/src/lib/hugo-markdown.ts

@@ -104,6 +104,11 @@ export interface HugoFrontMatter {
   status?: string;
   visibility?: string;
   summary_text?: string;
+  /**
+   * The timeline cuts this post's text short. Written only when true, so a
+   * consumer reads its presence rather than its value.
+   */
+  truncated?: boolean;
   link_url?: string;
   source_name?: string;
   source_url?: string;
@@ -111,6 +116,16 @@ export interface HugoFrontMatter {
   rating?: number | null;
   featured_at?: string | null;
   pinned_at?: string | null;
+  /**
+   * BCP 47 content language. Root bundles only — replies take the root's.
+   */
+  language?: string;
+  /**
+   * Opaque shared key linking posts that are translations of one another. Root
+   * bundles only. Meaningful within one export; carried across so a full-site
+   * restore keeps translated posts linked.
+   */
+  translation_group?: string;
   /**
    * Reply bundles only: the reply was published without announcing the Thread
    * on Latest. Round-tripped so a restore rebuilds the same ordering.
@@ -205,6 +220,7 @@ const FRONT_MATTER_KEY_ORDER: readonly string[] = [
   "status",
   "visibility",
   "summary_text",
+  "truncated",
   "link_url",
   "source_name",
   "source_url",

package/src/lib/icons.ts

@@ -24,17 +24,24 @@ function toPascalCase(name: string): string {
  * Get SVG markup for a Lucide icon by kebab-case name.
  *
  * @param name - Kebab-case icon name
+ * @param className - Extra classes for the `<svg>`, appended to Lucide's own.
+ *   `icon-fine` is the project's lighter stroke.
  * @returns SVG string or null when the icon is unknown
  *
  * @example
  * ```ts
  * getIconSvg("book-open");
+ * getIconSvg("funnel", "icon-fine");
  * ```
  */
-export function getIconSvg(name: string): string | null {
+export function getIconSvg(name: string, className?: string): string | null {
   const pascalName = toPascalCase(name);
   const svg = (lucideIcons as Record<string, string>)[pascalName];
-  return typeof svg === "string" ? svg : null;
+  if (typeof svg !== "string") return null;
+  if (!className) return svg;
+  // Lucide always ships a `class="lucide lucide-…"`, so extend it rather than
+  // adding a second class attribute the parser would drop.
+  return svg.replace(/class="([^"]*)"/, `class="$1 ${className}"`);
 }
 
 /**

package/src/lib/ids.ts

@@ -5,9 +5,12 @@ export const ID_PREFIX = {
   site: "sit",
   siteDomain: "sdm",
   post: "pst",
+  /** Shared key linking Posts that are translations of one another. */
+  translationGroup: "tgr",
   media: "med",
   uploadSession: "upl",
   collection: "col",
+  smartCollection: "smc",
   path: "pth",
   collectionDirectoryItem: "cdi",
   navItem: "nav",

package/src/lib/jant-docs.ts

@@ -0,0 +1,42 @@
+/**
+ * Links into the published documentation
+ *
+ * Everything under `docs/` is published on the Jant site: `docs/multilingual.md`
+ * is served at `/docs/multilingual`, lowercased and without the extension.
+ *
+ * The host is resolved once, here, so no call site writes a domain. Development
+ * builds point at the control plane running locally, which serves the docs
+ * being edited rather than the released ones.
+ */
+
+import { IS_VITE_DEV } from "./build-env.js";
+
+/** Docs host for released builds. */
+const DOCS_ORIGIN = "https://jant.me";
+
+/** Docs host during development. */
+const DEV_DOCS_ORIGIN = "https://jant-cloud.localtest.me";
+
+/** Documentation index for the current environment. */
+export const JANT_DOCS_BASE_URL = `${
+  IS_VITE_DEV ? DEV_DOCS_ORIGIN : DOCS_ORIGIN
+}/docs`;
+
+/**
+ * Build a link to one documentation page.
+ *
+ * @param page - Published page slug, optionally with a `#section` anchor. It is
+ *   the file name under `docs/`, lowercased and without `.md`. Omit it to link
+ *   the documentation index.
+ * @returns Absolute URL to that page on the current environment's docs site
+ * @example
+ * ```ts
+ * getJantDocsUrl("multilingual"); // "https://jant.me/docs/multilingual"
+ * getJantDocsUrl("configuration#required");
+ * // "https://jant.me/docs/configuration#required"
+ * getJantDocsUrl(); // "https://jant.me/docs"
+ * ```
+ */
+export function getJantDocsUrl(page = ""): string {
+  return page ? `${JANT_DOCS_BASE_URL}/${page}` : JANT_DOCS_BASE_URL;
+}

package/src/lib/lang-detect.ts

@@ -0,0 +1,308 @@
+/**
+ * Content language detection.
+ *
+ * A hand-written character-set voter, not a statistical model. It runs in the
+ * browser (in compose, for logged-in authors only — public pages load none of
+ * it) and on the server (for posts that arrive through the API, the Telegram
+ * bot, or MCP, where nobody picked a language).
+ *
+ * What it is good at, and what it is not:
+ *
+ * - Hangul and kana are near-unambiguous, so Korean and Japanese are reliable.
+ * - Simplified vs Traditional Chinese is decided by voting on characters that
+ *   exist in only one of the two. One sentence is usually plenty. Text written
+ *   the same way in both — `我今天很好` — is reported as Chinese of unsettled
+ *   variant, which is enough on a site publishing only one of them and
+ *   deliberately not enough on a site publishing both.
+ * - Latin script says "not CJK", nothing more. It resolves to a language only
+ *   when the site publishes exactly one non-CJK language.
+ * - Nothing at all is read out of a fragment. See `MIN_SIGNAL`: under a couple
+ *   of words the honest answer is the caller's default, not a coin toss that
+ *   changes with the next keystroke.
+ *
+ * The detector **never** returns an empty value or a language the site does
+ * not publish: it always answers with a member of `languages`, falling back to
+ * the caller's default. Its output is a *suggestion* the author can change —
+ * nothing here decides anything irreversibly.
+ */
+
+import { getCjkFontFromLanguageTag } from "../i18n/detect.js";
+
+/**
+ * Characters written only in Simplified Chinese.
+ *
+ * Every entry is checked to be absent from Traditional writing — a character
+ * that serves both (`后` as "empress", `台` in `台北`) would vote for the wrong
+ * side and has been left out, while its Traditional counterpart still votes.
+ */
+const SIMPLIFIED_ONLY =
+  "们这会说对时国学个来过现发经应关点无义与从门问间东车长马鸟鱼见贝页风飞头语话认识讲论议记让试该请读谁调谈变边达运还进远连" +
+  "适选递邮释钟银错锁闭开闻阅队阶阳阴陆陈险隐难静韩须顾频颜题类飘饭饮饰馆驻驾验骑骗体处备够夺奋妇妈宁宝实宽宾寻导尔尘尝尽层" +
+  "属岁岂岛币帅帮归当录彻忆态怀恋恶悬惊惧惨愤愿战户扩扫扬担拟挂挤挥换据摄击敌断旧显术机杀杂权条极构柜标树桥检楼欢欧残毁气汉" +
+  "汤沟泪洁济浏浅浆涛润涨渐渔渗湾湿满滨滤灭灯灵灾炉烦烧热营爱状犹狮独狱猎猪献猫环电画畅疗疯皱监盘矿码确础礼祸种积称稳穷窃竞" +
+  "笔筹简签粮紧纪纯纲纳纵纷纸线组细织终绍结绕绘给络绝统继绩绪续维综绿缓编缘缩缴网罗罚罢习联声职聪肃肠胀脑脱腊舰艰节苏药荐荡" +
+  "获萧蓝虏虚虽蚀蜡补装观规觉计订讨训讯词译诉诊证评诚误诸课谅谓谢谱贡财责贤败货质贩贪购贯贱贴贵贷贸费贺资赏赐赔赖赚赛赢赠赶" +
+  "趋践轨转轮软载较辅辈辉输辐辑辞迁迈违迟逊遗邓邻郑针钉钓钙钝钞钢钥钦钩钱钻铁铃铅铜铝铺链销锋锐锦键镇镜闪闯闲闷闹阀阁阵际隶" +
+  "随雾项顶预领颇颈颗颠饥饱饼馈驰驱驶骂骄鲁鲜鸡鸣鸦鸭鸽鹅鹰麦黄齐齿龄龙龟儿优传伤侦侧俭债倾偿储兰兴军农决净减凤凭则刘创剑剧" +
+  "劝办务动励劳势勋医华单卖卫厅历压厌厨参叶号叹吗启呐员呜响哑唤啸喷嘱团园围图圆场坏块坚坛垒垦堕墙壮壳复";
+
+/** Characters written only in Traditional Chinese. */
+const TRADITIONAL_ONLY =
+  "們這會說對時國學後個來過現發經應關點無義與從門問間東車長馬鳥魚見貝頁風飛頭語話認識講論議記讓試該請讀誰調談變邊達運還進遠" +
+  "連適選遞郵釋鐘銀錯鎖閉開聞閱隊階陽陰陸陳險隱難靜韓須顧頻顏題類飄飯飲飾館駐駕驗騎騙體處備夠奪奮婦媽寧寶實寬賓尋導爾塵嘗盡" +
+  "層屬歲豈島幣帥幫歸當錄徹憶態懷戀惡懸驚懼慘憤願戰戶擴掃揚擔擬掛擠揮換據攝擊敵斷舊顯術機殺雜權條極構櫃標樹橋檢樓歡歐殘毀氣" +
+  "漢湯溝淚潔濟瀏淺漿濤潤漲漸漁滲灣濕滿濱濾滅燈靈災爐煩燒熱營愛狀猶獅獨獄獵豬獻貓環電畫暢療瘋皺監盤礦碼確礎禮禍種積稱穩窮竊" +
+  "競筆籌簡簽糧緊紀純綱納縱紛紙線組細織終紹結繞繪給絡絕統繼績緒續維綜綠緩編緣縮繳網羅罰罷習聯聲職聰肅腸脹腦脫臘艦艱節蘇藥薦" +
+  "蕩獲蕭藍虜虛雖蝕蠟補裝觀規覺計訂討訓訊詞譯訴診證評誠誤諸課諒謂謝譜貢財責賢敗貨質販貪購貫賤貼貴貸貿費賀資賞賜賠賴賺賽贏贈" +
+  "趕趨踐軌轉輪軟載較輔輩輝輸輻輯辭遷邁違遲遜遺鄧鄰鄭針釘釣鈣鈍鈔鋼鑰欽鉤錢鑽鐵鈴鉛銅鋁鋪鏈銷鋒銳錦鍵鎮鏡閃闖閒悶鬧閥閣陣際" +
+  "隸隨霧項頂預領頗頸顆顛飢飽餅饋馳驅駛罵驕魯鮮雞鳴鴉鴨鴿鵝鷹麥黃齊齒齡龍龜兒優傳傷偵側儉債傾償儲蘭興軍農衝決淨減鳳憑劃則劉" +
+  "創劍劇勸辦務動勵勞勢勳醫華單賣衛廳歷壓厭廚參疊隻臺葉號嘆嗎啟吶員嗚響啞喚嘯噴囑團園圍圖圓場壞塊堅壇壘墾墮牆壯殼複";
+
+const SIMPLIFIED_SET = new Set(SIMPLIFIED_ONLY);
+const TRADITIONAL_SET = new Set(TRADITIONAL_ONLY);
+
+/**
+ * Script family a run of text is written in, before it meets the site's
+ * languages.
+ *
+ * `han` is Chinese whose variant the text does not settle: `我今天很好` and
+ * `哈哈哈哈` are written identically in Simplified and Traditional. It is a
+ * real answer, not a refusal — the text is certainly Chinese — and on a site
+ * that publishes only one of the two variants it is all the answer needed.
+ */
+export type DetectedScript =
+  "ko" | "ja" | "zh-Hans" | "zh-Hant" | "han" | "latin";
+
+interface ScriptCounts {
+  hangul: number;
+  kana: number;
+  han: number;
+  latin: number;
+  simplified: number;
+  traditional: number;
+}
+
+function countScripts(text: string): ScriptCounts {
+  const counts: ScriptCounts = {
+    hangul: 0,
+    kana: 0,
+    han: 0,
+    latin: 0,
+    simplified: 0,
+    traditional: 0,
+  };
+
+  for (const char of text) {
+    const code = char.codePointAt(0);
+    if (code === undefined) continue;
+
+    // Hangul syllables, Jamo, and compatibility Jamo.
+    if (
+      (code >= 0xac00 && code <= 0xd7a3) ||
+      (code >= 0x1100 && code <= 0x11ff) ||
+      (code >= 0x3130 && code <= 0x318f)
+    ) {
+      counts.hangul++;
+      continue;
+    }
+
+    // Hiragana, katakana, and katakana phonetic extensions.
+    if (
+      (code >= 0x3040 && code <= 0x309f) ||
+      (code >= 0x30a0 && code <= 0x30ff) ||
+      (code >= 0x31f0 && code <= 0x31ff)
+    ) {
+      counts.kana++;
+      continue;
+    }
+
+    // CJK Unified Ideographs, Extension A, and compatibility ideographs.
+    if (
+      (code >= 0x4e00 && code <= 0x9fff) ||
+      (code >= 0x3400 && code <= 0x4dbf) ||
+      (code >= 0xf900 && code <= 0xfaff)
+    ) {
+      counts.han++;
+      if (SIMPLIFIED_SET.has(char)) counts.simplified++;
+      else if (TRADITIONAL_SET.has(char)) counts.traditional++;
+      continue;
+    }
+
+    // Basic Latin letters plus the Latin-1 and Extended-A accented ranges.
+    if (
+      (code >= 0x41 && code <= 0x5a) ||
+      (code >= 0x61 && code <= 0x7a) ||
+      (code >= 0xc0 && code <= 0x24f)
+    ) {
+      counts.latin++;
+    }
+  }
+
+  return counts;
+}
+
+/**
+ * What a CJK character is worth against a Latin letter.
+ *
+ * A Han character is closer to a word than to a letter, and kana and Hangul
+ * sit in between — so counting characters straight would let a two-character
+ * quote outvote a paragraph. Three is the rough density ratio between CJK and
+ * Latin text, and it is the only number here that has to be approximate: it
+ * decides ties between scripts, not what any one script means.
+ */
+const CJK_WEIGHT = 3;
+
+/**
+ * How much evidence it takes before the detector will name a script at all.
+ *
+ * Ten points is four Han characters, or two English words. Below that the
+ * answer would swing on every keystroke — a composer that reads "H" as English
+ * and "He 说" as Chinese is not reading, it is twitching. Under the threshold
+ * the detector refuses and the caller keeps its own default, which is the
+ * language of the page the author is writing from.
+ */
+const MIN_SIGNAL = 10;
+
+/**
+ * Identify the script family a piece of text is written in.
+ *
+ * Exported for its own sake — the language-set resolution below is a separate
+ * concern, and testing the two apart keeps both honest.
+ *
+ * @param text - Plain text, typically a post body
+ * @returns The script family, or null when the text carries too little signal
+ * @example
+ * detectScript("これはテスト"); // "ja"
+ * detectScript("國學說這時"); // "zh-Hant"
+ * detectScript("我今天很好"); // "han" — Chinese, variant not settled
+ * detectScript("Hi"); // null — too short to be worth an answer
+ * detectScript("123 !!!"); // null
+ */
+export function detectScript(text: string): DetectedScript | null {
+  const counts = countScripts(text);
+  const cjk = (counts.hangul + counts.kana + counts.han) * CJK_WEIGHT;
+
+  // Which script the text is *mostly* in, not merely which one appears in it:
+  // an English paragraph that quotes a Chinese phrase is still English, and
+  // before this comparison a single Han character spoke for the whole post.
+  if (cjk >= counts.latin && cjk >= MIN_SIGNAL) {
+    // Korean mixes Hangul with Han; Japanese mixes kana with Han. Neither
+    // borrows the other's syllabary, so either one present settles it.
+    if (counts.hangul > 0) return "ko";
+    if (counts.kana > 0) return "ja";
+    if (counts.simplified > counts.traditional) return "zh-Hans";
+    if (counts.traditional > counts.simplified) return "zh-Hant";
+    // Han with no distinctive character either way, or the same number on each
+    // side. Which variant this is, the text does not say; that it is Chinese,
+    // it says clearly. Report that much and let the caller weigh it against the
+    // languages the site actually publishes.
+    return "han";
+  }
+
+  return counts.latin >= MIN_SIGNAL ? "latin" : null;
+}
+
+/**
+ * Read one of the site's languages out of a piece of text, or admit that the
+ * text does not say.
+ *
+ * The distinction is the whole point of this function existing next to
+ * `detectContentLanguage`: a caller that substitutes a default cannot tell
+ * "this is English" from "I could not tell, here is your default", and a
+ * composer that reports the second as the first is lying to the author.
+ *
+ * @param text - Plain text, typically a post body
+ * @param options - The languages the site publishes
+ * @returns A tag from `options.languages`, or null when the text does not
+ *   settle on one of them
+ * @example
+ * readContentLanguage("國學說這時會對後", {
+ *   languages: ["zh-Hans", "zh-Hant", "en"],
+ * }); // "zh-Hant"
+ * readContentLanguage("Hi", { languages: ["zh-Hans", "en"] }); // null
+ */
+export function readContentLanguage(
+  text: string,
+  options: { languages: readonly string[] },
+): string | null {
+  const { languages } = options;
+  if (languages.length === 0) return null;
+
+  const script = detectScript(text);
+  if (!script) return null;
+
+  if (script === "latin") {
+    // Latin script only says "not CJK". That names a language only when there
+    // is exactly one candidate; with English and French configured, guessing
+    // between them from the alphabet alone would be a coin toss.
+    const nonCjk = languages.filter((tag) => !getCjkFontFromLanguageTag(tag));
+    return nonCjk.length === 1 ? (nonCjk[0] as string) : null;
+  }
+
+  if (script === "han") {
+    // Same shape as the Latin case: the text narrowed it to Chinese but not to
+    // a variant, so it names a language only when the site publishes one of
+    // them. A site running both Simplified and Traditional gets no answer,
+    // which is the honest one — the text genuinely does not say.
+    const chinese = languages.filter((tag) => {
+      const profile = getCjkFontFromLanguageTag(tag);
+      return profile === "zh-Hans" || profile === "zh-Hant";
+    });
+    return chinese.length === 1 ? (chinese[0] as string) : null;
+  }
+
+  // No match means the site does not publish the detected script — say nothing
+  // rather than invent a language the author never configured.
+  return (
+    languages.find((tag) => getCjkFontFromLanguageTag(tag) === script) ?? null
+  );
+}
+
+/**
+ * Suggest which of the site's languages a piece of text is written in.
+ *
+ * @param text - Plain text, typically a post body
+ * @param options - The languages the site publishes, and what to answer when
+ *   the text gives no usable signal
+ * @returns A tag from `options.languages`, always
+ * @example
+ * detectContentLanguage("國學說這時會對後", {
+ *   languages: ["zh-Hans", "zh-Hant", "en"],
+ *   fallback: "zh-Hans",
+ * }); // "zh-Hant"
+ */
+export function detectContentLanguage(
+  text: string,
+  options: { languages: readonly string[]; fallback: string },
+): string {
+  return readContentLanguage(text, options) ?? options.fallback;
+}
+
+/**
+ * Suggest the language a new Post should be stored with, when nobody said.
+ *
+ * Only ever fills a blank: an explicit choice is the author's and is never
+ * second-guessed here. Returns null on a site that does not publish more than
+ * one language, because nothing is stamped before the feature is turned on.
+ *
+ * @param options - Text to read, the site's languages, and its primary one
+ * @returns Canonical tag from `languages`, or null when the site is single-language
+ * @example
+ * suggestPostLanguage({
+ *   text: "Hello there",
+ *   languages: ["zh-Hans", "en"],
+ *   primary: "zh-Hans",
+ * }); // "en"
+ */
+export function suggestPostLanguage(options: {
+  text?: string | null;
+  languages: readonly string[];
+  primary: string;
+}): string | null {
+  const { text, languages, primary } = options;
+
+  if (languages.length === 0) return null;
+  if (!text?.trim()) return primary;
+
+  return detectContentLanguage(text, { languages, fallback: primary });
+}

package/src/lib/media-helpers.ts

@@ -58,9 +58,21 @@ export function buildMediaMap(
               fit: "scale-down",
             })
           : mediaUrl;
-        const posterUrl = m.posterKey
+        // A poster is a still frame at whatever resolution the source video
+        // had, so it needs the same transform as any other image — without it
+        // a 4K clip puts a multi-megabyte PNG in the feed. Matches the limits
+        // `toMediaView` uses for the same field.
+        const posterRawUrl = m.posterKey
           ? getMediaUrl(m.posterKey, publicUrl, sitePathPrefix)
           : null;
+        const posterUrl = posterRawUrl
+          ? getImageUrl(posterRawUrl, imageTransformUrl, {
+              width: 640,
+              quality: 80,
+              format: "auto",
+              fit: "scale-down",
+            })
+          : null;
         return {
           id: m.id,
           url: mediaUrl,