@jant/core 0.6.16 → 0.7.1

package/src/lib/per-language-surfaces.ts

@@ -0,0 +1,67 @@
+/**
+ * Which reader surfaces exist once per language.
+ *
+ * Mirrors the `langGet()` table in `routes/pages/language.tsx` — the two must
+ * change together. Kept in its own module, free of server imports, because the
+ * client needs the same answer: `viewPath()` uses it to decide whether a link
+ * carries the current view's language prefix, and getting it wrong in either
+ * direction is a bug you can see — a missing prefix drops the reader into
+ * another language, an extra one lands on a 404.
+ *
+ * Everything not listed here — the dashboard, auth, collection editors, and
+ * post permalinks — has one address site-wide.
+ */
+
+/** Surfaces served per language at exactly this path. */
+const PER_LANGUAGE_SURFACES = new Set([
+  "/",
+  "/feed",
+  "/latest",
+  "/featured",
+  "/archive",
+  "/search",
+  "/subscribe",
+  "/collections",
+]);
+
+/**
+ * Surfaces whose sub-paths are all per-language too. `/collections/` is absent
+ * on purpose: aggregate selections and their feeds are, but nothing else
+ * nested under it is.
+ */
+const PER_LANGUAGE_SURFACE_PREFIXES = ["/latest/", "/featured/", "/archive/"];
+
+const COLLECTIONS_PREFIX = "/collections/";
+
+/** `/collections/{selection}` and its feed, and nothing else under it. */
+function isCollectionSelectionSurface(path: string): boolean {
+  const rest = path.slice(COLLECTIONS_PREFIX.length);
+  if (!rest) return false;
+
+  const segments = rest.split("/");
+  if (segments[0] === "") return false;
+  if (segments.length === 1) return true;
+  return segments.length === 2 && segments[1] === "feed";
+}
+
+/**
+ * Whether a path exists in every language's view.
+ *
+ * @param path - Internal app path, without any language prefix. A query string
+ *   or fragment is ignored, so callers can pass a built link as-is.
+ * @returns True when `/ja{path}` is a page rather than a 404
+ * @example
+ * isPerLanguageSurface("/archive?media=any"); // true — /ja/archive exists
+ * isPerLanguageSurface("/collections/a+b/feed"); // true — /ja/collections/a+b/feed exists
+ * isPerLanguageSurface("/settings/language"); // false — the dash is one place
+ */
+export function isPerLanguageSurface(path: string): boolean {
+  const bare = path.split(/[?#]/, 1)[0] ?? path;
+  if (PER_LANGUAGE_SURFACES.has(bare)) return true;
+  if (bare.startsWith(COLLECTIONS_PREFIX)) {
+    return isCollectionSelectionSurface(bare);
+  }
+  return PER_LANGUAGE_SURFACE_PREFIXES.some((prefix) =>
+    bare.startsWith(prefix),
+  );
+}

package/src/lib/post-body-html.ts

@@ -8,6 +8,7 @@
 
 import type { JSONContent } from "@tiptap/core";
 import { upgradeLegacyFootnotes } from "./footnotes.js";
+import { fillRequiredContent } from "./markdown-manager.js";
 import {
   renderTiptapDocument,
   type TiptapRenderResult,
@@ -50,8 +51,9 @@ export function renderPostBodyHtml(postId: string, body: string): string {
 }
 
 /**
- * Normalize recognized historical footnotes and render the current HTML
- * projection in one parse pass.
+ * Normalize recognized historical footnotes, fill in children the schema
+ * requires (an empty list item gets its paragraph), and render the current
+ * HTML projection in one parse pass.
  *
  * @param postId - Immutable post TypeID
  * @param body - Canonical TipTap JSON
@@ -73,10 +75,15 @@ export function tryPreparePostBodyHtml(
     }
 
     const upgraded = upgradeLegacyFootnotes(parsed);
+    const doc = fillRequiredContent(upgraded.doc);
+    const canonical = JSON.stringify(doc);
     return {
       ok: true,
-      body: upgraded.upgraded ? JSON.stringify(upgraded.doc) : body,
-      html: renderTiptapDocument(upgraded.doc, { namespace: postId }),
+      body:
+        upgraded.upgraded || canonical !== JSON.stringify(upgraded.doc)
+          ? canonical
+          : body,
+      html: renderTiptapDocument(doc, { namespace: postId }),
       upgradedLegacyFootnotes: upgraded.upgraded,
     };
   } catch (error) {

package/src/lib/post-meta.ts

@@ -97,6 +97,25 @@ function getDescriptionCandidate(post: Post): string {
   return "";
 }
 
+/**
+ * What to call a Post in a list, when it may have no title of its own.
+ *
+ * Notes are usually untitled, so falling back to the slug would show readers
+ * and authors a URL fragment where they expect a sentence. The chain is the
+ * same one browser titles and Open Graph tags already use: title, then the
+ * quoted text, then the summary, then the opening of the body, then a link's
+ * domain.
+ *
+ * @param post - The Post to name
+ * @returns A short plain-text label, or an empty string when there is nothing
+ *   to derive one from
+ * @example
+ * getPostDisplayTitle(untitledNote); // "An untitled note about espresso."
+ */
+export function getPostDisplayTitle(post: Post): string {
+  return getTitleCandidate(post);
+}
+
 export interface PostMeta {
   title: string;
   description?: string;

package/src/lib/render.tsx

@@ -9,9 +9,20 @@ import type { Context } from "hono";
 import type { Child } from "hono/jsx";
 import type { SiteLayoutProps } from "../types.js";
 import { SETTINGS_KEYS } from "./constants.js";
-import { BaseLayout, type ToastProps } from "../ui/layouts/BaseLayout.js";
+import {
+  BaseLayout,
+  type PageFeedLink,
+  type ToastProps,
+} from "../ui/layouts/BaseLayout.js";
 import { SiteLayout } from "../ui/layouts/SiteLayout.js";
 import type { NavigationData } from "./navigation.js";
+import {
+  buildComposeLanguages,
+  buildLanguageSwitcher,
+  getViewLang,
+  type LanguageAlternate,
+  type LanguageSwitcherOption,
+} from "./view-language.js";
 
 export interface RenderPublicPageOptions {
   /** Page title for <title> tag */
@@ -45,6 +56,23 @@ export interface RenderPublicPageOptions {
    * thread root).
    */
   canonicalHref?: string;
+  /**
+   * `hreflang` alternates for this page. List surfaces pass
+   * `buildSurfaceAlternates(c)`; a post passes its translations. Pages that
+   * exist once for the whole site pass nothing.
+   */
+  alternateLanguages?: LanguageAlternate[];
+  /**
+   * The feed this page publishes, for `<link rel="alternate">` autodiscovery.
+   * Set on pages with a feed of their own — a collection, the archive — so a
+   * reader's extension finds that feed rather than only the site-wide ones.
+   */
+  pageFeed?: PageFeedLink;
+  /**
+   * Language switcher entries. Defaults to the current surface in each of the
+   * site's languages; a post overrides it with its translations.
+   */
+  languageSwitcher?: LanguageSwitcherOption[];
   /** Navigation data (from getNavigationData) */
   navData: NavigationData;
   /** Page content JSX to render inside SiteLayout */
@@ -57,14 +85,24 @@ export interface RenderPublicPageOptions {
   toast?: ToastProps;
   /** Whether to render the shared compose dialog shell */
   showComposeDialog?: boolean;
-  /** Override the site-wide crawler setting for sensitive utility pages. */
-  noindex?: boolean;
+  /**
+   * Override the site-wide crawler setting for this page. `true` means
+   * `noindex, nofollow`; `"follow"` keeps the URL unindexed while leaving its
+   * links crawlable. See `BaseLayoutProps["noindex"]`.
+   */
+  noindex?: boolean | "follow";
   /** Whether to render the site header */
   showHeader?: boolean;
   /** Whether to render the home branding credit after the site footer */
   showHomeBranding?: boolean;
   /** When set, the mobile compose FAB pre-selects this collection. */
   composeCollectionId?: string;
+  /**
+   * Content language of the page the composer opens from, for its default.
+   * List surfaces leave this unset and get the view language; a post page
+   * passes its post's language, since its URL carries no view prefix.
+   */
+  composeContextLanguage?: string | null;
 }
 
 /**
@@ -99,6 +137,9 @@ export function renderPublicPage(c: Context, options: RenderPublicPageOptions) {
     articleModifiedTime,
     jsonLd,
     canonicalHref,
+    alternateLanguages,
+    pageFeed,
+    languageSwitcher,
     navData,
     content,
     pageChrome,
@@ -109,6 +150,7 @@ export function renderPublicPage(c: Context, options: RenderPublicPageOptions) {
     showHeader,
     showHomeBranding,
     composeCollectionId,
+    composeContextLanguage,
   } = options;
 
   // Use siteDescription as meta description fallback when not explicitly provided
@@ -123,9 +165,10 @@ export function renderPublicPage(c: Context, options: RenderPublicPageOptions) {
     links: navData.links,
     currentPath: navData.currentPath,
     sitePathPrefix: navData.sitePathPrefix,
+    basePath: navData.basePath,
     isAuthenticated: navData.isAuthenticated,
     collections: navData.collections,
-    siteAvatarUrl: navData.siteAvatarUrl,
+    siteAvatarThumbUrl: navData.siteAvatarThumbUrl,
     showHeaderAvatar: navData.showHeaderAvatar,
     siteDescriptionHtml: navData.siteDescriptionHtml,
     siteFooterHtml: navData.siteFooterHtml,
@@ -141,11 +184,14 @@ export function renderPublicPage(c: Context, options: RenderPublicPageOptions) {
       allSettings[SETTINGS_KEYS.DISCOVERY_SLASH_COMMAND_AT],
     ),
     composeCollectionId,
+    languageSwitcher: languageSwitcher ?? buildLanguageSwitcher(c),
+    composeLanguages: buildComposeLanguages(c),
+    composeContextLanguage: composeContextLanguage ?? getViewLang(c),
   };
   const faviconUrl = appConfig.siteAvatarUrl || undefined;
   const faviconVersion = appConfig.faviconVersion || undefined;
-  const resolvedNoindex = noindex ?? appConfig.noindex;
-
+  // `noindex` is passed straight through: BaseLayout reads the site-wide
+  // setting from this same context and is the single place the two resolve.
   return c.html(
     <BaseLayout
       title={title}
@@ -162,9 +208,11 @@ export function renderPublicPage(c: Context, options: RenderPublicPageOptions) {
       articleModifiedTime={articleModifiedTime}
       jsonLd={jsonLd}
       canonicalHref={canonicalHref}
+      alternateLanguages={alternateLanguages}
+      pageFeed={pageFeed}
       faviconUrl={faviconUrl}
       faviconVersion={faviconVersion}
-      noindex={resolvedNoindex}
+      noindex={noindex}
       isAuthenticated={navData.isAuthenticated}
       toast={toast}
     >

package/src/lib/resolve-config.ts

@@ -12,21 +12,78 @@
 import type { Bindings } from "../types/bindings.js";
 import type { AppConfig } from "../types/config.js";
 import { CONFIG_FIELDS } from "../types/config.js";
-import type { FeedKind } from "../types/constants.js";
+import type { ArchiveLayout, FeedKind } from "../types/constants.js";
 import { ASSET_BASE_SEGMENT, getPublicAssetBasePath } from "./asset-path.js";
+import { resolveDiscoverMode } from "./discover.js";
 import {
   getAuthSecret,
   getConfiguredSingleSiteUrl,
   getConfiguredStorageDriver,
+  getDiscoverDefault,
   getEnvString,
 } from "./env.js";
-import { getPublicUrlForProvider, getMediaUrl } from "./image.js";
+import { parseLanguageList } from "../i18n/locales.js";
+import { getPublicUrlForProvider, getMediaUrl, getImageUrl } from "./image.js";
 import { normalizeTimeZone } from "./timezones.js";
 import { getSiteOrigin, getSitePathPrefix, normalizeSiteUrl } from "./url.js";
 
+/**
+ * Whether an empty stored value means "never configured" for this field.
+ *
+ * The test is whether the editor could have produced the empty value, and it
+ * mirrors what `normalizeConfigEditorDefinitionValue` accepts. A boolean takes
+ * only `true` or `false`; a number has to parse; an enum has to name one of its
+ * options. None of those can be stored empty, so an empty row for one of them
+ * is not a choice anybody made — it comes from a path that skips validation,
+ * and a snapshot's `db.sql`, replayed as raw SQL, is exactly that. Read as a
+ * configured value it silences the environment variable the operator did set,
+ * for as long as the row exists.
+ *
+ * Text is the opposite: clearing a description or a footer is an ordinary edit,
+ * so an empty value there is a decision and keeps its precedence. So is an enum
+ * that lists `""` among its options, the way `DASHBOARD_LANGUAGE` does, and one
+ * whose options come from a runtime source, where nothing here can rule it
+ * out.
+ *
+ * @param field - Config registry entry for the key being resolved
+ * @returns True when an empty stored value should fall through to env/default
+ *
+ * @example
+ * ```ts
+ * isUnsetWhenEmpty(CONFIG_FIELDS.NOINDEX); // true  (boolean)
+ * isUnsetWhenEmpty(CONFIG_FIELDS.SITE_FOOTER); // false (string)
+ * ```
+ */
+function isUnsetWhenEmpty(
+  field: (typeof CONFIG_FIELDS)[keyof typeof CONFIG_FIELDS],
+): boolean {
+  if (!("editor" in field)) return false;
+  const editor = field.editor;
+  switch (editor.type) {
+    case "boolean":
+    case "number":
+      return true;
+    case "enum":
+      // Only a fixed option list proves the value is impossible. `""` is a real
+      // choice for `DASHBOARD_LANGUAGE`, which offers it, and an enum drawing
+      // its options from a runtime source cannot rule it out either.
+      return (
+        "options" in editor &&
+        !(editor.options as readonly string[]).includes("")
+      );
+    default:
+      return false;
+  }
+}
+
 /**
  * Resolve a single config value following priority rules.
  *
+ * Settings saved in the dashboard outrank the environment, which outranks the
+ * default. The exception is an empty boolean or numeric value — see
+ * {@link isUnsetWhenEmpty}, which explains why that is absence rather than
+ * choice.
+ *
  * @param key - CONFIG_FIELDS key
  * @param allSettings - DB settings map
  * @param env - Worker bindings
@@ -43,7 +100,10 @@ function resolve(
 
   // User-configurable: DB > ENV > Default
   if (!field.envOnly && Object.hasOwn(allSettings, key)) {
-    return allSettings[key] ?? "";
+    const stored = allSettings[key] ?? "";
+    if (stored !== "" || !isUnsetWhenEmpty(field)) {
+      return stored;
+    }
   }
 
   // ENV > Default
@@ -147,6 +207,13 @@ function parseFeedKind(value: string, fallback: FeedKind): FeedKind {
   return value === "latest" || value === "featured" ? value : fallback;
 }
 
+function parseArchiveLayout(
+  value: string,
+  fallback: ArchiveLayout,
+): ArchiveLayout {
+  return value === "list" || value === "grid" ? value : fallback;
+}
+
 /**
  * Build a complete AppConfig from environment bindings and DB settings.
  *
@@ -198,6 +265,7 @@ export function resolveConfig(
   // Resolve avatar URL from storage key
   const siteAvatar = allSettings["SITE_AVATAR"] ?? "";
   let siteAvatarUrl = "";
+  let siteAvatarThumbUrl = "";
   if (siteAvatar) {
     const publicUrl = getPublicUrlForProvider(
       storageDriver,
@@ -206,6 +274,17 @@ export function resolveConfig(
       localPublicUrl,
     );
     siteAvatarUrl = getMediaUrl(siteAvatar, publicUrl, sitePathPrefix);
+    // The header and drawer marks render this at 32px and 24px, on every page,
+    // in parallel with the render-blocking stylesheet. An untransformed avatar
+    // is whatever the author uploaded — commonly a 512px PNG — so it competes
+    // for the critical path with tens of times the bytes it can use. 128px
+    // still covers a high-DPR header and a theme that enlarges the mark.
+    siteAvatarThumbUrl = getImageUrl(siteAvatarUrl, imageTransformUrl, {
+      width: 128,
+      quality: 80,
+      format: "auto",
+      fit: "scale-down",
+    });
   }
 
   // Description is "explicit" when set in DB or ENV (not just the default)
@@ -216,6 +295,16 @@ export function resolveConfig(
     ? !!dbDescription
     : !!envDescription;
 
+  // The owner's stored choice and the deployment's default stay apart, and
+  // the registry default must not stand in for either: an absent row is what
+  // lets `noindex` decide, and an absent binding is what makes Discover
+  // opt-in for a self-hosted site.
+  const discoverStoredValue = allSettings["DISCOVER"];
+  const discoverDefaultValue = getDiscoverDefault(env);
+  const noindex = demoMode || resolve("NOINDEX", allSettings, env) === "true";
+  const rssFeedsEnabled =
+    resolve("RSS_FEEDS_ENABLED", allSettings, env) === "true";
+
   return {
     // Site identity (DB > ENV > Default)
     siteName: resolve("SITE_NAME", allSettings, env),
@@ -223,19 +312,34 @@ export function resolveConfig(
     siteDescriptionExplicit,
     siteLanguage: resolve("SITE_LANGUAGE", allSettings, env),
     dashboardLanguage: resolve("DASHBOARD_LANGUAGE", allSettings, env),
-    cjkSerifFont: resolve("CJK_SERIF_FONT", allSettings, env),
+    multilingualEnabled:
+      resolve("MULTILINGUAL_ENABLED", allSettings, env) === "true",
+    additionalLanguages: parseLanguageList(
+      resolve("ADDITIONAL_LANGUAGES", allSettings, env),
+    ),
     mainRssFeed: parseFeedKind(
       resolve("MAIN_RSS_FEED", allSettings, env),
       "featured",
     ),
+    archiveDefaultLayout: parseArchiveLayout(
+      resolve("ARCHIVE_DEFAULT_LAYOUT", allSettings, env),
+      "list",
+    ),
     timeZone: normalizeTimeZone(resolve("TIME_ZONE", allSettings, env)),
     siteFooter: resolve("SITE_FOOTER", allSettings, env),
     showJantBrandingOnHome:
       resolve("SHOW_JANT_BRANDING_ON_HOME", allSettings, env) === "true",
-    noindex: demoMode || resolve("NOINDEX", allSettings, env) === "true",
+    noindex,
+    discover: resolveDiscoverMode({
+      storedValue: discoverStoredValue,
+      defaultValue: discoverDefaultValue,
+      demoMode,
+      noindex,
+      rssFeedsEnabled,
+    }),
     publicApiEnabled:
       resolve("PUBLIC_API_ENABLED", allSettings, env) === "true",
-    rssFeedsEnabled: resolve("RSS_FEEDS_ENABLED", allSettings, env) === "true",
+    rssFeedsEnabled,
 
     // Infrastructure (ENV only)
     siteUrl,
@@ -318,6 +422,7 @@ export function resolveConfig(
     siteAvatar,
     showHeaderAvatar: allSettings["SHOW_HEADER_AVATAR"] === "true",
     siteAvatarUrl,
+    siteAvatarThumbUrl,
     faviconVersion: allSettings["SITE_FAVICON_VERSION"] ?? "",
 
     // Rate limiting (ENV only). Defaults are conservative enough for a