@jant/core 0.6.16 → 0.7.0

package/src/types/app-context.ts

@@ -53,6 +53,13 @@ export interface AppVariables {
    * `c.var.rateLimiter.check(...)` instead of caring which impl is used.
    */
   rateLimiter: RateLimiter;
+  /**
+   * Language whose browsing view is being served, set by the language routes
+   * when the URL carries a language prefix (`/en/archive`). Undefined on the
+   * root view, which shows the primary language — or every language, when
+   * multilingual content is off.
+   */
+  viewLang?: string;
 }
 
 export type App = Hono<{ Bindings: Bindings; Variables: AppVariables }>;

package/src/types/bindings.ts

@@ -37,11 +37,14 @@ export interface Bindings {
   SITE_LANGUAGE?: EnvBindingValue;
   DASHBOARD_LANGUAGE?: EnvBindingValue;
   MAIN_RSS_FEED?: EnvBindingValue;
+  ARCHIVE_DEFAULT_LAYOUT?: EnvBindingValue;
   TIME_ZONE?: EnvBindingValue;
   SITE_FOOTER?: EnvBindingValue;
   NOINDEX?: EnvBindingValue;
   PUBLIC_API_ENABLED?: EnvBindingValue;
   RSS_FEEDS_ENABLED?: EnvBindingValue;
+  DISCOVER?: EnvBindingValue;
+  DISCOVER_PING_URL?: EnvBindingValue;
   R2_PUBLIC_URL?: EnvBindingValue;
   IMAGE_TRANSFORM_URL?: EnvBindingValue;
   DEMO_EMAIL?: EnvBindingValue;

package/src/types/config.ts

@@ -4,10 +4,12 @@
  * Single Source of Truth for all configuration fields.
  */
 
+import type { DiscoverMode } from "../lib/discover.js";
 import {
   MAX_SITE_DESCRIPTION_LENGTH,
   MAX_SITE_FOOTER_LENGTH,
   MAX_SITE_NAME_LENGTH,
+  type ArchiveLayout,
   type FeedKind,
 } from "./constants.js";
 
@@ -125,13 +127,37 @@ export const CONFIG_FIELDS = {
       options: ["", "en", "zh-Hans", "zh-Hant"],
     },
   },
-  CJK_SERIF_FONT: {
-    defaultValue: "off",
+  // Multilingual content. Both keys are deliberately DB-only:
+  //
+  // - No `envKeys`: an env var could flip multilingual on without the confirm
+  //   step that stamps existing posts with the primary language, and every
+  //   unstamped post would vanish from the root view. Adding a language through
+  //   env would likewise skip the URL-prefix conflict check.
+  // - No `editor`: `PUT /api/settings` and the generic Config Editor both gate
+  //   on `"editor" in field`, so omitting it leaves exactly one writer — the
+  //   language service, which owns the ordering these settings depend on.
+  //
+  // `configEditorLink` keeps them findable in settings search without making
+  // them directly writable.
+  MULTILINGUAL_ENABLED: {
+    defaultValue: "false",
     envOnly: false,
-    envKeys: ["CJK_SERIF_FONT"],
-    editor: {
-      type: "enum",
-      options: ["off", "zh-Hans", "zh-Hant", "ja", "ko"],
+    configEditorLink: {
+      type: "boolean",
+      settingsPath: "/settings/language",
+      display: "value",
+    },
+  },
+  // Comma-separated canonical BCP 47 tags, in switcher order. Never contains
+  // the primary language. Comma-separated rather than JSON because tags cannot
+  // contain commas: no escaping, readable in the settings table, order-preserving.
+  ADDITIONAL_LANGUAGES: {
+    defaultValue: "",
+    envOnly: false,
+    configEditorLink: {
+      type: "string",
+      settingsPath: "/settings/language",
+      display: "configured",
     },
   },
   MAIN_RSS_FEED: {
@@ -140,6 +166,15 @@ export const CONFIG_FIELDS = {
     envKeys: ["MAIN_RSS_FEED"],
     editor: { type: "enum", options: ["featured", "latest"] },
   },
+  // The archive is the widest of Featured / Latest / All, and the other two
+  // render as timelines. `list` keeps the trio consistent; `grid` turns the
+  // page back into a tile catalogue.
+  ARCHIVE_DEFAULT_LAYOUT: {
+    defaultValue: "list",
+    envOnly: false,
+    envKeys: ["ARCHIVE_DEFAULT_LAYOUT"],
+    editor: { type: "enum", options: ["list", "grid"] },
+  },
   // Environment-only (deployment/infrastructure config)
   DEFAULT_THEME: {
     defaultValue: "tufte",
@@ -192,7 +227,7 @@ export const CONFIG_FIELDS = {
     envKeys: ["DEMO_MODE"],
   },
   PAGE_SIZE: {
-    defaultValue: "50",
+    defaultValue: "25",
     envOnly: false,
     envKeys: ["PAGE_SIZE"],
     editor: { type: "number", min: 1, max: 100, step: 1 },
@@ -432,6 +467,30 @@ export const CONFIG_FIELDS = {
     envKeys: ["RSS_FEEDS_ENABLED"],
     editor: { type: "boolean" },
   },
+  // No default value, and deliberately no `editor`. "Never chosen" has to stay
+  // tellable apart from an explicit choice — an unset site falls through to
+  // `noindex` and then to the deployment default, an explicit one does not —
+  // and Config Editor has no way to show a field whose default is "unset": it
+  // requires every editable field to resolve to a concrete valid value. The
+  // effective mode is derived in `lib/discover.ts`, and the checkbox in
+  // settings/general is where this is edited.
+  //
+  // The binding is read as this deployment's default rather than as the
+  // site's answer, which is how hosted Jant lists its fleet while a
+  // self-hosted site, with nothing set anywhere, stays out until asked.
+  DISCOVER: {
+    defaultValue: "",
+    envOnly: false,
+    envKeys: ["DISCOVER"],
+  },
+  // What the last announcement to the directory came to. State, not
+  // configuration — nobody edits this — so it is internal like
+  // `ONBOARDING_STATUS`. Shape and reasoning in `lib/discover-ping.ts`.
+  DISCOVER_ANNOUNCE_STATE: {
+    defaultValue: "",
+    envOnly: false,
+    internal: true,
+  },
   DISCOVERY_COMPOSE_OPEN_SHORTCUT_AT: {
     defaultValue: "",
     envOnly: false,
@@ -452,11 +511,6 @@ export const CONFIG_FIELDS = {
     envOnly: false,
     internal: true,
   },
-  DELETE_CSRF_TOKEN: {
-    defaultValue: "",
-    envOnly: false,
-    internal: true,
-  },
 
   // GitHub Sync (DB-only, managed via GitHub Sync settings page)
   GITHUB_SYNC_ENABLED: {
@@ -683,6 +737,10 @@ export interface AppConfig {
   siteDescription: string;
   /** true only when description is set in DB or ENV (not just the default) */
   siteDescriptionExplicit: boolean;
+  /**
+   * The site's content language, and — once multilingual content is on — its
+   * primary language: the one served from the unprefixed root URLs.
+   */
   siteLanguage: string;
   /**
    * Admin dashboard UI locale. Empty string means "follow the content
@@ -690,14 +748,29 @@ export interface AppConfig {
    * the translated catalog locales ("en", "zh-Hans", "zh-Hant").
    */
   dashboardLanguage: string;
-  /** Optional CJK font fallback when the content language has no profile. */
-  cjkSerifFont: string;
+  /** Whether the site serves per-language browsing views. */
+  multilingualEnabled: boolean;
+  /**
+   * Canonical BCP 47 tags served under a URL prefix, in switcher order. Never
+   * includes `siteLanguage`. Retained when multilingual is switched off so
+   * turning it back on restores the same setup — and so the old prefixes can
+   * still redirect rather than 404.
+   */
+  additionalLanguages: string[];
   mainRssFeed: FeedKind;
+  /** Layout `/archive` uses when the URL names no explicit layout. */
+  archiveDefaultLayout: ArchiveLayout;
   /** Canonical IANA timezone identifier used for date/time display. */
   timeZone: string;
   siteFooter: string;
   showJantBrandingOnHome: boolean;
   noindex: boolean;
+  /**
+   * Effective Jant Discover mode this site's feeds declare. Derived from the
+   * `DISCOVER` setting plus the demo, `noindex`, and feeds-enabled rules in
+   * `lib/discover.ts` — never the stored value on its own.
+   */
+  discover: DiscoverMode;
   /** Whether published content can be read from JSON APIs without authentication. */
   publicApiEnabled: boolean;
   /** Whether the site publishes its Atom feed endpoints. */
@@ -757,8 +830,14 @@ export interface AppConfig {
   // Site appearance (DB internal)
   siteAvatar: string;
   showHeaderAvatar: boolean;
-  /** Derived: getMediaUrl(siteAvatar, publicUrl) */
+  /** Derived: getMediaUrl(siteAvatar, publicUrl) — full resolution, for the
+   *  social card, the settings editor, and anything that syncs the canonical
+   *  asset. */
   siteAvatarUrl: string;
+  /** Derived: `siteAvatarUrl` sized for the header and drawer marks, which
+   *  render it at 32px and 24px. Falls back to `siteAvatarUrl` when no image
+   *  transform is configured. */
+  siteAvatarThumbUrl: string;
   faviconVersion: string;
 
   // Rate limiting (ENV only)

package/src/types/constants.ts

@@ -14,22 +14,102 @@ export type Visibility = (typeof VISIBILITIES)[number];
 export const FEED_KINDS = ["latest", "featured"] as const;
 export type FeedKind = (typeof FEED_KINDS)[number];
 
-export const SORT_ORDERS = [
-  "newest",
-  "oldest",
-  "rating_desc",
-  "rating_asc",
+/**
+ * Layouts the archive page can render in. `list` renders the same timeline the
+ * rest of the nav trio uses; `grid` renders the tile catalogue.
+ *
+ * Named "layout", not "view": on the archive, `view` is reserved for the
+ * saved-selection concept, and the URL param follows the same split
+ * (`?layout=grid`, with `?view=` kept only as the legacy spelling).
+ */
+export const ARCHIVE_LAYOUTS = ["list", "grid"] as const;
+export type ArchiveLayout = (typeof ARCHIVE_LAYOUTS)[number];
+
+/**
+ * Visibility values a signed-out reader may select on the archive.
+ *
+ * `featured` is a virtual member: it is a separate flag rather than a stored
+ * visibility, and it lives here because the filter bar presents the two as one
+ * dimension.
+ *
+ * `private` is deliberately absent. It names a set only the author can see, so
+ * a reader who asks for it has to be told so — handing back a different set
+ * under the same name is the one answer that is never right.
+ */
+export const PUBLIC_ARCHIVE_VISIBILITIES = [
+  "public",
+  "featured",
+  "latest_hidden",
 ] as const;
-export type SortOrder = (typeof SORT_ORDERS)[number];
 
-export const COLLECTION_SORT_ORDERS = [
-  "newest",
-  "oldest",
-  "rating_desc",
+/** Every visibility the author can select, in filter-bar order. */
+export const ARCHIVE_VISIBILITIES = [
+  ...PUBLIC_ARCHIVE_VISIBILITIES,
+  "private",
 ] as const;
-export type CollectionSortOrder = (typeof COLLECTION_SORT_ORDERS)[number];
 
-export const NAV_ITEM_TYPES = ["link", "system", "collection", "page"] as const;
+export type ArchiveVisibility = (typeof ARCHIVE_VISIBILITIES)[number];
+
+/**
+ * The range a `year` filter may name, inclusive at both ends.
+ *
+ * Unix timestamps start in 1970, so anything at or below it is a parse failure
+ * rather than a very old archive.
+ *
+ * The ceiling is not pedantry. A year is translated into a pair of bounds with
+ * `Date.UTC`, which returns `NaN` past year 275760 — and a `NaN` bound is a
+ * comparison every row silently fails, so the page renders empty with nothing
+ * to explain it. Four digits is the largest year a post can honestly carry, and
+ * it is bounded in three places at once: the URL parser, the stored condition's
+ * validator, and the table CHECK in both dialects.
+ */
+export const EARLIEST_FILTERABLE_YEAR = 1971;
+export const LATEST_FILTERABLE_YEAR = 9999;
+
+/**
+ * How a chronological query orders its results.
+ *
+ * `newest` and `oldest` read whichever time axis `PostFilters.sortBy` selects,
+ * so "newest" on the activity axis means "last gained a post" and on the
+ * published axis means "published last".
+ *
+ * Not to be confused with the archive's `?sort=`, which names a *time axis*
+ * (`published` / `updated`) and always runs newest-first. Two vocabularies, and
+ * mixing them is how month headers stop agreeing with the order beneath them.
+ */
+export const SORT_ORDERS = ["newest", "oldest", "rating_desc"] as const;
+export type SortOrder = (typeof SORT_ORDERS)[number];
+
+/**
+ * The orders a collection offers its readers — the same three, deliberately.
+ *
+ * Kept as its own name because the two vocabularies answer different questions
+ * (one orders a query, one is stored on a collection row and shown in a menu),
+ * and pointing them at one array is what keeps them from drifting apart the way
+ * the smart collection's fourth order once did.
+ */
+export const COLLECTION_SORT_ORDERS = SORT_ORDERS;
+export type CollectionSortOrder = SortOrder;
+
+/**
+ * How a smart collection orders the posts its conditions gather.
+ *
+ * Identical to a manual collection's orders, and for the same reasons: on both,
+ * `newest` means the Thread that last gained a post, not the Thread published
+ * last. A smart collection briefly carried a fourth order named `updated` that
+ * said the same thing in different words; folding it into `newest` left one
+ * menu the reader can learn once.
+ */
+export const SMART_COLLECTION_SORT_ORDERS = COLLECTION_SORT_ORDERS;
+export type SmartCollectionSortOrder = CollectionSortOrder;
+
+export const NAV_ITEM_TYPES = [
+  "link",
+  "system",
+  "collection",
+  "smart_collection",
+  "page",
+] as const;
 export type NavItemType = (typeof NAV_ITEM_TYPES)[number];
 
 export const NAV_ITEM_PLACEMENTS = ["header", "more"] as const;
@@ -41,6 +121,7 @@ export const SYSTEM_NAV_KEY_VALUES = [
   "collections",
   "archive",
   "rss",
+  "subscribe",
   "settings",
 ] as const;
 export type SystemNavKey = (typeof SYSTEM_NAV_KEY_VALUES)[number];
@@ -59,14 +140,31 @@ export const SYSTEM_NAV_KEYS = {
   collections: {
     defaultLabel: "Collections",
     url: "/collections",
-    defaultPlacement: "header",
+    // The header switches between how much of one list you see (Featured /
+    // Latest / All). Collections is a different axis — what a post is about —
+    // and readers reach that through the collection tags on posts they are
+    // already reading, so it starts one level down instead of widening the
+    // header for everyone.
+    defaultPlacement: "more",
   },
   archive: {
-    defaultLabel: "Archive",
+    defaultLabel: "All",
     url: "/archive",
     defaultPlacement: "header",
   },
-  rss: { defaultLabel: "Feed", url: "/feed", defaultPlacement: "more" },
+  // Two entries, two audiences. `rss` links straight at the Atom document, for
+  // an author whose readers already run a feed reader; `subscribe` links at the
+  // page that explains the feeds, for everyone else. Repointing `rss` at
+  // /subscribe instead of adding this would have destroyed the first case, and
+  // left a key named `rss` addressing an HTML page — nav data themes read.
+  rss: { defaultLabel: "RSS", url: "/feed", defaultPlacement: "more" },
+  subscribe: {
+    defaultLabel: "Subscribe",
+    url: "/subscribe",
+    // A once-in-a-reader's-lifetime utility page, not a section to come back
+    // and read, so it sits with Settings rather than beside Featured and All.
+    defaultPlacement: "more",
+  },
   settings: {
     defaultLabel: "Settings",
     url: "/settings",
@@ -81,6 +179,32 @@ export const SYSTEM_NAV_KEYS = {
   }
 >;
 
+/**
+ * The system nav entries that exist only while RSS feeds do.
+ *
+ * `rss` addresses the Atom document; `subscribe` addresses the page that
+ * explains it, which 404s without feeds. Both disappear from the rendered
+ * navigation when feeds are switched off — while staying in the database, so
+ * placement and custom labels survive being switched back on.
+ */
+export const FEED_NAV_KEYS = [
+  "rss",
+  "subscribe",
+] as const satisfies readonly SystemNavKey[];
+
+/**
+ * Whether a system nav key is one of the feed entries.
+ *
+ * @param key - A system nav key, or nothing for a non-system item
+ * @returns Whether the entry depends on feeds being enabled
+ * @example
+ * isFeedNavKey("subscribe"); // true
+ * isFeedNavKey("archive"); // false
+ */
+export function isFeedNavKey(key: string | null | undefined): boolean {
+  return (FEED_NAV_KEYS as readonly string[]).includes(key ?? "");
+}
+
 export interface DefaultNavigationProfile {
   version: number;
   systemKeys: readonly SystemNavKey[];
@@ -96,9 +220,24 @@ export const DEFAULT_NAVIGATION_PROFILES = {
     version: 1,
     systemKeys: ["featured", "collections", "archive", "rss", "settings"],
   },
+  // Featured and All sit next to each other because they are the same list at
+  // two widths; version 1 split that pair with Collections, which reads as a
+  // third unrelated section rather than the wide end of one range.
+  2: {
+    version: 2,
+    systemKeys: ["featured", "archive", "collections", "rss", "settings"],
+  },
+  // `rss` handed a browser a screen of Atom XML, which is a dead end for a
+  // reader who does not already know what to do with it. New sites point at
+  // /subscribe instead; existing rows keep `rss`, and an author who wants the
+  // new entry turns it on beside the old one in Appearance.
+  3: {
+    version: 3,
+    systemKeys: ["featured", "archive", "collections", "subscribe", "settings"],
+  },
 } as const satisfies Record<number, DefaultNavigationProfile>;
 
-export const DEFAULT_NAVIGATION_PROFILE_VERSION = 1 as const;
+export const DEFAULT_NAVIGATION_PROFILE_VERSION = 3 as const;
 export const DEFAULT_NAVIGATION_PROFILE =
   DEFAULT_NAVIGATION_PROFILES[DEFAULT_NAVIGATION_PROFILE_VERSION];
 
@@ -131,6 +270,23 @@ export type StorageDriver = (typeof STORAGE_DRIVERS)[number];
 export const PATH_KINDS = ["slug", "alias", "redirect", "archive"] as const;
 export type PathKind = (typeof PATH_KINDS)[number];
 
+/**
+ * Row kinds the collections directory can hold.
+ *
+ * A `collection` row points at a collection and carries no text of its own; a
+ * `divider` and a `link` carry text and point at nothing. The table CHECK in
+ * both dialects is generated from this list, so a new kind is one edit here
+ * plus the shape branch that describes which columns it fills.
+ */
+export const COLLECTION_DIRECTORY_ENTRY_TYPES = [
+  "collection",
+  "smart_collection",
+  "divider",
+  "link",
+] as const;
+export type CollectionDirectoryEntryType =
+  (typeof COLLECTION_DIRECTORY_ENTRY_TYPES)[number];
+
 /** How long a collection nav item stays "fresh" after new content is added */
 export const COLLECTION_FRESHNESS_WINDOW_SECONDS = 48 * 60 * 60;
 
@@ -142,3 +298,19 @@ export type SiteDomainKind = (typeof SITE_DOMAIN_KINDS)[number];
 
 export const SITE_MEMBER_ROLES = ["owner", "admin", "editor"] as const;
 export type SiteMemberRole = (typeof SITE_MEMBER_ROLES)[number];
+
+export const UPLOAD_SESSION_STATES = [
+  "pending",
+  "uploaded",
+  "completed",
+  "aborted",
+  "failed",
+] as const;
+export type UploadSessionState = (typeof UPLOAD_SESSION_STATES)[number];
+
+/** How a stored object is served: rendered in place, or downloaded. */
+export const CONTENT_DISPOSITIONS = ["inline", "attachment"] as const;
+export type ContentDisposition = (typeof CONTENT_DISPOSITIONS)[number];
+
+export const GITHUB_APP_ACCOUNT_TYPES = ["User", "Organization"] as const;
+export type GithubAppAccountType = (typeof GITHUB_APP_ACCOUNT_TYPES)[number];

package/src/types/entities.ts

@@ -3,10 +3,13 @@
  */
 
 import type {
+  CollectionDirectoryEntryType,
   Format,
   Status,
   Visibility,
   CollectionSortOrder,
+  SmartCollectionSortOrder,
+  ArchiveLayout,
   NavItemType,
   NavItemPlacement,
   SystemNavKey,
@@ -17,6 +20,10 @@ import type {
   SiteMemberRole,
 } from "./constants.js";
 
+import type { PostFilterSelection } from "../lib/filter-dimensions.js";
+
+export type { CollectionDirectoryEntryType };
+
 export interface Site {
   id: string;
   key: string;
@@ -66,6 +73,15 @@ export interface Post {
   previewProvider: string | null;
   replyToId: string | null;
   threadId: string;
+  /**
+   * BCP 47 content language, canonical form. Uniform across a Thread. `null`
+   * only until the site first enables multilingual content.
+   */
+  language: string | null;
+  /**
+   * Shared key for Posts that are translations of one another. Roots only.
+   */
+  translationGroupId: string | null;
   /** Reply published without announcing it on Latest. Always false on roots. */
   quietReply: boolean;
   publishedAt: number | null;
@@ -141,13 +157,60 @@ export interface CollectionDirectoryCollection extends Collection {
   recentActivityAt: number;
 }
 
-export type CollectionDirectoryEntryType = "collection" | "divider" | "link";
+/**
+ * A collection whose members are decided by conditions rather than by tagging.
+ *
+ * To a reader this is a collection: a root-level address, a title, a
+ * description, a list of posts, a feed. The asymmetries are permanent and
+ * deliberate — nothing can be added to it by hand, nothing pinned, nothing
+ * reordered — so every "add this post to a collection" surface has to leave it
+ * out. See `selection` for what decides membership.
+ */
+export interface SmartCollection {
+  id: string;
+  siteId: string;
+  slug: string;
+  title: string;
+  description: string | null;
+  /** The conditions, in the shared dimension vocabulary. Empty = every post. */
+  selection: PostFilterSelection;
+  sort: SmartCollectionSortOrder;
+  /** `null` follows the site's configured archive layout. */
+  layout: ArchiveLayout | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface SmartCollectionDirectoryEntry extends SmartCollection {
+  threadCount: number;
+  /**
+   * Newest activity among the threads the conditions match, or the smart
+   * collection's own `updatedAt` when they match nothing.
+   *
+   * The same measure `CollectionDirectoryCollection` carries, on the same
+   * definition, because the two sit in one list and a reader compares them.
+   */
+  recentActivityAt: number;
+}
+
+/**
+ * One entry in the collections directory, either kind.
+ *
+ * The two are told apart by `kind`, not by which optional field happens to be
+ * present. Surfaces that treat them alike — the directory, the navigation
+ * picker, the command palette — take this; surfaces where the difference
+ * matters take one or the other.
+ */
+export type AnyCollectionEntry =
+  | { kind: "manual"; collection: CollectionDirectoryCollection }
+  | { kind: "smart"; smartCollection: SmartCollectionDirectoryEntry };
 
 export interface CollectionDirectoryEntry {
   id: string;
   siteId: string;
   type: CollectionDirectoryEntryType;
   collectionId: string | null;
+  smartCollectionId: string | null;
   label: string | null;
   url: string | null;
   description: string | null;
@@ -163,10 +226,12 @@ export interface CollectionDirectoryItem {
   url?: string | null;
   description?: string | null;
   collection?: CollectionDirectoryCollection;
+  smartCollection?: SmartCollectionDirectoryEntry;
 }
 
 export interface CollectionsDirectoryData {
   collections: CollectionDirectoryCollection[];
+  smartCollections: SmartCollectionDirectoryEntry[];
   items: CollectionDirectoryItem[];
   directoryItems: CollectionDirectoryEntry[];
 }
@@ -183,9 +248,24 @@ export interface NavItem {
   type: NavItemType;
   systemKey?: SystemNavKey;
   collectionId?: string;
+  smartCollectionId?: string;
   postId?: string;
+  /**
+   * Author's override, or `""` when the item follows whatever it points at.
+   *
+   * Empty is the normal state: a page or collection item shows its target's
+   * current title, a built-in item shows its translated default. Only a label
+   * the author typed is stored here, and it then wins in every language view.
+   */
   label: string;
   url: string;
+  /**
+   * Current title of the post or collection this item points at, resolved at
+   * read time. The display label when `label` is empty — see
+   * `getNavItemDisplayLabel`. Absent for `link` and `system` items, which have
+   * no target row to follow.
+   */
+  targetTitle?: string;
   placement: NavItemPlacement;
   position: string;
   createdAt: number;
@@ -210,6 +290,7 @@ export interface PathRecord {
   kind: PathKind;
   postId: string | null;
   collectionId: string | null;
+  smartCollectionId: string | null;
   redirectToPath: string | null;
   redirectType: 301 | 302 | null;
   archiveQuery: string | null;
@@ -241,5 +322,10 @@ export interface ThreadTimelineContext {
   /** Published replies immediately before latest, in chronological order. */
   trailingReplies: Post[];
   latestReply: Post;
+  /**
+   * First reply the fold hides, which is where the gap link points. Null when
+   * nothing is hidden. Fetched for its address only — never rendered.
+   */
+  firstHiddenReply: Post | null;
   totalReplyCount: number;
 }