@jant/core 0.6.14 → 0.6.16

package/src/lib/feed-policy.ts

@@ -0,0 +1,64 @@
+import type { Post } from "../types.js";
+import { now, toISOString } from "./time.js";
+
+/** Cache policy for dynamic Atom feed responses. */
+export const RSS_FEED_CACHE_CONTROL = "public, max-age=60";
+
+/**
+ * Convert an RSS publication delay into the exclusive upper bound expected by
+ * Post service queries.
+ *
+ * Posts published exactly `delaySeconds` ago are eligible. Because publication
+ * timestamps use whole seconds while `publishedBefore` is exclusive, the bound
+ * is one second after the latest eligible timestamp.
+ *
+ * @param delaySeconds - Non-negative publication delay in seconds
+ * @param currentTime - Current Unix timestamp, injectable for deterministic use
+ * @returns Exclusive `publishedBefore` timestamp for RSS queries
+ * @example
+ * ```ts
+ * getRssPublishedBefore(300, 1_000); // 701, so publishedAt <= 700 is eligible
+ * ```
+ */
+export function getRssPublishedBefore(
+  delaySeconds: number,
+  currentTime = now(),
+): number {
+  return currentTime - delaySeconds + 1;
+}
+
+/**
+ * Resolve the Atom `updated` timestamp for a Thread entry from content that is
+ * actually present in the feed.
+ *
+ * @param root - Thread root used as a fallback when no Thread rows are loaded
+ * @param thread - Eligible Thread Posts included in the Atom entry
+ * @param additionalTimestamps - Other entry updates, such as Collection membership
+ * @returns Latest update timestamp as an ISO 8601 string
+ * @example
+ * ```ts
+ * getFeedEntryUpdatedAt(root, [root, reply], [collectedAt]);
+ * ```
+ */
+export function getFeedEntryUpdatedAt(
+  root: Pick<Post, "publishedAt" | "updatedAt">,
+  thread: readonly Pick<Post, "publishedAt" | "updatedAt">[] | undefined,
+  additionalTimestamps: readonly (number | null | undefined)[] = [],
+): string {
+  let updatedAt = Math.max(root.updatedAt, root.publishedAt ?? root.updatedAt);
+
+  for (const post of thread ?? []) {
+    updatedAt = Math.max(
+      updatedAt,
+      post.updatedAt,
+      post.publishedAt ?? post.updatedAt,
+    );
+  }
+  for (const timestamp of additionalTimestamps) {
+    if (timestamp !== null && timestamp !== undefined) {
+      updatedAt = Math.max(updatedAt, timestamp);
+    }
+  }
+
+  return toISOString(updatedAt);
+}

package/src/lib/feed.ts

@@ -11,6 +11,7 @@
  */
 
 import type { FeedData, FeedPostView, MediaView, PostView } from "../types.js";
+import { getLinkPreviewProviderLabel } from "./link-preview.js";
 import { extractDisplayDomain } from "./url.js";
 import { getMediaCategory } from "./upload.js";
 
@@ -40,6 +41,49 @@ function escapeCdata(str: string): string {
   return str.replaceAll("]]>", "]]]]><![CDATA[>");
 }
 
+/**
+ * Resolve a URL for use outside the feed document's browser context.
+ *
+ * Feed readers do not consistently resolve root-relative URLs found inside
+ * Atom HTML content or enclosure attributes, so every non-fragment URL must
+ * carry its own origin.
+ */
+function toAbsoluteFeedUrl(url: string, siteUrl: string): string {
+  const normalizedUrl = url.trim();
+  if (!normalizedUrl || normalizedUrl.startsWith("#")) return normalizedUrl;
+
+  try {
+    const baseUrl = siteUrl.endsWith("/") ? siteUrl : `${siteUrl}/`;
+    return new URL(normalizedUrl, baseUrl).toString();
+  } catch {
+    return normalizedUrl;
+  }
+}
+
+/**
+ * Resolve navigational and media URL attributes inside trusted post HTML.
+ *
+ * Fragment-only links stay local to the rendered feed entry so footnotes and
+ * other in-entry references continue to work.
+ */
+function absolutizeFeedHtmlUrls(html: string, siteUrl: string): string {
+  return html.replaceAll(
+    /(\s)(href|poster|src)=(["'])([^"']*)\3/gi,
+    (
+      match,
+      whitespace: string,
+      attribute: string,
+      quote: string,
+      url: string,
+    ) => {
+      const absoluteUrl = toAbsoluteFeedUrl(url, siteUrl);
+      return absoluteUrl
+        ? `${whitespace}${attribute}=${quote}${absoluteUrl}${quote}`
+        : match;
+    },
+  );
+}
+
 /**
  * Strip embedded content that is unsafe or unsupported in feed readers.
  *
@@ -144,6 +188,35 @@ function renderRatingHtml(rating: number): string {
   return `<p>${filled}${empty} ${rating}/5</p>`;
 }
 
+/**
+ * Render a Link post preview as feed-safe HTML.
+ *
+ * Feed readers commonly strip CSS overlays and embedded players, so video
+ * previews use a linked thumbnail plus a visible provider-aware action.
+ * Non-video Link previews keep the linked thumbnail without a video label.
+ */
+function renderLinkPreviewForFeed(post: PostView, siteUrl: string): string {
+  if (post.format !== "link") return "";
+
+  const imageUrl = post.previewImageUrl?.trim();
+  const linkUrl = post.url?.trim();
+  if (!imageUrl || !linkUrl) return "";
+
+  const isVideo = post.previewKind?.trim().toLowerCase() === "video";
+  const providerLabel = getLinkPreviewProviderLabel(post.previewProvider);
+  const fallbackAlt = isVideo
+    ? providerLabel
+      ? `${providerLabel} video`
+      : "Video preview"
+    : "Link preview";
+  const altText = post.title?.trim() || fallbackAlt;
+  const caption = isVideo
+    ? `<figcaption><a href="${escapeXml(linkUrl)}">▶ ${providerLabel ? `Watch on ${providerLabel}` : "Watch video"}</a></figcaption>`
+    : "";
+
+  return `<figure><a href="${escapeXml(linkUrl)}"><img src="${escapeXml(toAbsoluteFeedUrl(imageUrl, siteUrl))}" alt="${escapeXml(altText)}"/></a>${caption}</figure>`;
+}
+
 function formatFeedBytes(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
@@ -203,9 +276,13 @@ function buildAttachmentLinkText(
  *   and duration metadata when known. Text attachments link to the rendered
  *   preview page when a post permalink is available.
  */
-function renderMediaItem(item: MediaView, postPermalinkUrl?: string): string {
+function renderMediaItem(
+  item: MediaView,
+  siteUrl: string,
+  postPermalinkUrl?: string,
+): string {
   const category = getMediaCategory(item.mimeType);
-  const url = escapeXml(item.url);
+  const url = escapeXml(toAbsoluteFeedUrl(item.url, siteUrl));
   const name = item.originalName ?? "";
   const altText = item.altText ?? "";
   const caption = item.altText?.trim() || "";
@@ -223,7 +300,10 @@ function renderMediaItem(item: MediaView, postPermalinkUrl?: string): string {
   }
 
   if (category === "video") {
-    const poster = item.posterUrl || item.thumbnailUrl;
+    const poster = toAbsoluteFeedUrl(
+      item.posterUrl || item.thumbnailUrl,
+      siteUrl,
+    );
     const dims =
       item.width && item.height
         ? ` width="${item.width}" height="${item.height}"`
@@ -272,11 +352,12 @@ function renderMediaItem(item: MediaView, postPermalinkUrl?: string): string {
  */
 function renderMediaForFeed(
   media: MediaView[],
+  siteUrl: string,
   postPermalinkUrl?: string,
 ): string {
   if (media.length === 0) return "";
   return media
-    .map((item) => renderMediaItem(item, postPermalinkUrl))
+    .map((item) => renderMediaItem(item, siteUrl, postPermalinkUrl))
     .join("\n");
 }
 
@@ -289,6 +370,7 @@ function renderMediaForFeed(
  */
 function buildSinglePostContent(
   post: PostView,
+  siteUrl: string,
   permalinkUrl?: string,
   options: SinglePostContentOptions = {},
 ): string {
@@ -314,11 +396,18 @@ function buildSinglePostContent(
     }
   }
 
+  const linkPreviewHtml = renderLinkPreviewForFeed(post, siteUrl);
+  if (linkPreviewHtml) {
+    parts.push(linkPreviewHtml);
+  }
+
   if (post.bodyHtml) {
-    parts.push(stripUnsafeFeedHtml(post.bodyHtml));
+    parts.push(
+      absolutizeFeedHtmlUrls(stripUnsafeFeedHtml(post.bodyHtml), siteUrl),
+    );
   }
 
-  const mediaHtml = renderMediaForFeed(post.media, permalinkUrl);
+  const mediaHtml = renderMediaForFeed(post.media, siteUrl, permalinkUrl);
   if (mediaHtml) {
     parts.push(mediaHtml);
   }
@@ -353,7 +442,7 @@ function buildFeedContent(
   siteUrl: string,
   permalinkUrl?: string,
 ): string {
-  const rootContent = buildSinglePostContent(post, permalinkUrl);
+  const rootContent = buildSinglePostContent(post, siteUrl, permalinkUrl);
   const replies = post.threadReplies;
 
   if (!replies || replies.length === 0) {
@@ -368,7 +457,9 @@ function buildFeedContent(
     parts.push(
       `<p><small><time datetime="${escapeXml(reply.publishedAt)}">${escapeXml(reply.publishedAtFormatted)}</time></small></p>`,
     );
-    parts.push(buildSinglePostContent(reply, replyPermalink, { inline: true }));
+    parts.push(
+      buildSinglePostContent(reply, siteUrl, replyPermalink, { inline: true }),
+    );
   }
 
   return parts.join("\n");
@@ -421,7 +512,7 @@ export function defaultFeedRenderer(data: FeedData): string {
           const titleAttr = m.originalName
             ? ` title="${escapeXml(m.originalName)}"`
             : "";
-          return `\n    <link rel="enclosure" type="${escapeXml(m.mimeType)}" href="${escapeXml(m.url)}"${lengthAttr}${titleAttr}/>`;
+          return `\n    <link rel="enclosure" type="${escapeXml(m.mimeType)}" href="${escapeXml(toAbsoluteFeedUrl(m.url, siteUrl))}"${lengthAttr}${titleAttr}/>`;
         })
         .join("");
 
@@ -438,7 +529,18 @@ export function defaultFeedRenderer(data: FeedData): string {
     })
     .join("");
 
-  const now = new Date().toISOString();
+  // The feed's own <updated> is the newest entry timestamp, not the current
+  // time — stamping "now" on every render tells every reader the feed changed
+  // on every poll, which is both untrue and useless for change detection.
+  // ISO 8601 from toISOString() is UTC and zero-padded, so lexical max is
+  // chronological max. Empty feeds fall back to now, since Atom requires it.
+  const feedUpdated =
+    posts
+      .map((post) => post.feedUpdatedAt ?? post.updatedAt)
+      .reduce<
+        string | null
+      >((latest, value) => (latest === null || value > latest ? value : latest), null) ??
+    new Date().toISOString();
 
   return `<?xml version="1.0" encoding="UTF-8"?>
 <feed xmlns="http://www.w3.org/2005/Atom">
@@ -447,7 +549,7 @@ export function defaultFeedRenderer(data: FeedData): string {
   <link href="${escapeXml(siteUrl)}" rel="alternate"/>
   <link href="${escapeXml(selfUrl)}" rel="self"/>
   <id>${escapeXml(selfUrl)}</id>
-  <updated>${now}</updated>
+  <updated>${feedUpdated}</updated>
   ${entries}
 </feed>`;
 }

package/src/lib/footnotes.ts

@@ -18,6 +18,16 @@ export interface FootnoteDefinitionTokenData {
   contentMarkdown: string;
 }
 
+export interface LegacyFootnoteUpgradeResult {
+  doc: JSONContent;
+  upgraded: boolean;
+}
+
+interface LegacyFootnoteReference {
+  label: string;
+  node: JSONContent;
+}
+
 export function normalizeFootnoteLabel(label: unknown): string {
   if (typeof label !== "string") return "";
   return label.trim().replace(/\s+/g, " ");
@@ -82,6 +92,260 @@ export function normalizeFootnoteArtifacts(doc: JSONContent): JSONContent {
   return content.length === doc.content.length ? doc : { ...doc, content };
 }
 
+function getLinkHref(node: JSONContent): string {
+  const linkMarks = (node.marks ?? []).filter((mark) => mark.type === "link");
+  if (linkMarks.length !== 1) return "";
+
+  const href = linkMarks[0]?.attrs?.href;
+  return typeof href === "string" ? href.trim() : "";
+}
+
+function decodeHashTarget(href: string): string {
+  if (!href.startsWith("#")) return "";
+
+  try {
+    return decodeURIComponent(href.slice(1));
+  } catch {
+    return href.slice(1);
+  }
+}
+
+function normalizeLegacyTargetId(value: string): string {
+  return value.replace(/^user-content-/i, "").toLowerCase();
+}
+
+function getLegacyReferenceLabel(node: JSONContent): string {
+  if (node.type !== "text" || typeof node.text !== "string") return "";
+
+  const text = node.text.trim();
+  const displayMatch = text.match(/^\[\^?([^\]\n]+)\]$/);
+  const label = normalizeFootnoteLabel(displayMatch?.[1] ?? text);
+  if (!label) return "";
+
+  const targetId = normalizeLegacyTargetId(decodeHashTarget(getLinkHref(node)));
+  const expectedTargetId = `fn-${getFootnoteDomId(label)}`.toLowerCase();
+  return targetId === expectedTargetId ? label : "";
+}
+
+function collectLegacyReferences(
+  node: JSONContent,
+  references: LegacyFootnoteReference[],
+): void {
+  const label = getLegacyReferenceLabel(node);
+  if (label) {
+    references.push({ label, node });
+    return;
+  }
+
+  for (const child of node.content ?? []) {
+    collectLegacyReferences(child, references);
+  }
+}
+
+function isBacklinkText(value: string | undefined): boolean {
+  return /^(?:↩(?:︎)?|↵)(?:\s*\d+)?$/.test(value?.trim() ?? "");
+}
+
+function getLegacyBacklinkLabel(
+  node: JSONContent,
+  labels: readonly string[],
+): string {
+  if (node.type !== "text" || !isBacklinkText(node.text)) return "";
+
+  const targetId = normalizeLegacyTargetId(decodeHashTarget(getLinkHref(node)));
+  if (!targetId.startsWith("fnref-")) return "";
+
+  for (const label of labels) {
+    const base = `fnref-${getFootnoteDomId(label)}`.toLowerCase();
+    const occurrence = targetId.startsWith(`${base}-`)
+      ? targetId.slice(base.length + 1)
+      : "";
+    if (targetId === base || /^\d+$/.test(occurrence)) {
+      return label;
+    }
+  }
+
+  return "";
+}
+
+function collectLegacyBacklinkLabels(
+  node: JSONContent,
+  labels: readonly string[],
+  found: Set<string>,
+): void {
+  const label = getLegacyBacklinkLabel(node, labels);
+  if (label) {
+    found.add(getFootnoteLabelKey(label));
+    return;
+  }
+
+  for (const child of node.content ?? []) {
+    collectLegacyBacklinkLabels(child, labels, found);
+  }
+}
+
+function removeLegacyBacklinks(
+  node: JSONContent,
+  label: string,
+): JSONContent | null {
+  if (
+    getFootnoteLabelKey(getLegacyBacklinkLabel(node, [label])) ===
+    getFootnoteLabelKey(label)
+  ) {
+    return null;
+  }
+
+  if (!node.content) return node;
+
+  const content = node.content.flatMap((child) => {
+    const normalized = removeLegacyBacklinks(child, label);
+    return normalized ? [normalized] : [];
+  });
+
+  if (content.length === node.content.length) {
+    const unchanged = content.every(
+      (child, index) => child === node.content?.[index],
+    );
+    if (unchanged) return node;
+  }
+
+  return content.length > 0 ? { ...node, content } : { ...node, content: [] };
+}
+
+function replaceLegacyReferences(
+  node: JSONContent,
+  labelsByNode: Map<JSONContent, string>,
+): JSONContent {
+  const label = labelsByNode.get(node);
+  if (label) {
+    return { type: "footnoteReference", attrs: { label } };
+  }
+
+  if (!node.content) return node;
+
+  const content = node.content.map((child) =>
+    replaceLegacyReferences(child, labelsByNode),
+  );
+  const unchanged = content.every(
+    (child, index) => child === node.content?.[index],
+  );
+  return unchanged ? node : { ...node, content };
+}
+
+function hasCanonicalFootnoteNode(node: JSONContent): boolean {
+  if (node.type === "footnoteReference" || node.type === "footnoteDefinition") {
+    return true;
+  }
+
+  return (node.content ?? []).some(hasCanonicalFootnoteNode);
+}
+
+/**
+ * Upgrades the historical footnote shape that old rich-text pastes stored as
+ * ordinary fragment links plus a trailing ordered list.
+ *
+ * Conversion is deliberately all-or-nothing. The document must end in an
+ * `hr` and ordered list, every definition item must contain a matching
+ * `#fnref-*` backlink, and every `#fn-*` reference must have exactly one
+ * definition label. This keeps normal fragment links and numbered lists
+ * untouched.
+ *
+ * @param doc - Parsed TipTap document
+ * @returns The canonical document and whether a legacy footnote set changed
+ * @example
+ * ```ts
+ * const result = upgradeLegacyFootnotes({
+ *   type: "doc",
+ *   content: [],
+ * });
+ * // { doc: { type: "doc", content: [] }, upgraded: false }
+ * ```
+ */
+export function upgradeLegacyFootnotes(
+  doc: JSONContent,
+): LegacyFootnoteUpgradeResult {
+  if (
+    doc.type !== "doc" ||
+    !Array.isArray(doc.content) ||
+    doc.content.length < 3 ||
+    hasCanonicalFootnoteNode(doc)
+  ) {
+    return { doc, upgraded: false };
+  }
+
+  const definitionList = doc.content.at(-1);
+  const separator = doc.content.at(-2);
+  if (
+    definitionList?.type !== "orderedList" ||
+    separator?.type !== "horizontalRule" ||
+    !Array.isArray(definitionList.content) ||
+    definitionList.content.length === 0 ||
+    definitionList.content.some((item) => item.type !== "listItem")
+  ) {
+    return { doc, upgraded: false };
+  }
+
+  const bodyNodes = doc.content.slice(0, -2);
+  const references: LegacyFootnoteReference[] = [];
+  for (const node of bodyNodes) collectLegacyReferences(node, references);
+  if (references.length === 0) return { doc, upgraded: false };
+
+  const labelsByKey = new Map<string, string>();
+  for (const reference of references) {
+    const key = getFootnoteLabelKey(reference.label);
+    if (!labelsByKey.has(key)) labelsByKey.set(key, reference.label);
+  }
+  const labels = [...labelsByKey.values()].sort(
+    (left, right) =>
+      getFootnoteDomId(right).length - getFootnoteDomId(left).length,
+  );
+  if (labels.length !== definitionList.content.length) {
+    return { doc, upgraded: false };
+  }
+
+  const definitions: JSONContent[] = [];
+  const definedLabels = new Set<string>();
+  for (const item of definitionList.content) {
+    const backlinkLabels = new Set<string>();
+    collectLegacyBacklinkLabels(item, labels, backlinkLabels);
+    if (backlinkLabels.size !== 1) return { doc, upgraded: false };
+
+    const key = [...backlinkLabels][0];
+    if (!key) return { doc, upgraded: false };
+    const label = labelsByKey.get(key);
+    if (!label || definedLabels.has(key)) return { doc, upgraded: false };
+
+    definedLabels.add(key);
+    const content = (item.content ?? []).flatMap((child) => {
+      const normalized = removeLegacyBacklinks(child, label);
+      return normalized ? [normalized] : [];
+    });
+    definitions.push({
+      type: "footnoteDefinition",
+      attrs: { label },
+      content: content.length > 0 ? content : [{ type: "paragraph" }],
+    });
+  }
+
+  if (definedLabels.size !== labelsByKey.size) {
+    return { doc, upgraded: false };
+  }
+
+  const labelsByNode = new Map(
+    references.map((reference) => [reference.node, reference.label] as const),
+  );
+  return {
+    doc: {
+      ...doc,
+      content: [
+        ...bodyNodes.map((node) => replaceLegacyReferences(node, labelsByNode)),
+        ...definitions,
+      ],
+    },
+    upgraded: true,
+  };
+}
+
 /**
  * Parses one Markdown footnote definition from the start of `src`.
  *

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

@@ -30,6 +30,8 @@ export async function buildSyncSiteConfig(c: {
     siteDescription: appConfig.siteDescription,
     siteLanguage: appConfig.siteLanguage,
     showJantBrandingOnHome: appConfig.showJantBrandingOnHome,
+    publicApiEnabled: appConfig.publicApiEnabled,
+    rssFeedsEnabled: appConfig.rssFeedsEnabled,
     mainRssFeed: appConfig.mainRssFeed,
     siteFooter: appConfig.siteFooter,
     showHeaderAvatar: appConfig.showHeaderAvatar,

package/src/lib/hugo-markdown.ts

@@ -16,8 +16,9 @@
 // ---------------------------------------------------------------------------
 
 /**
- * Per-collection membership metadata. Preserved verbatim on round-trip so
- * curators keep their collected_at / position / pinned_at ordering.
+ * Per-Thread collection membership metadata. Current exports write this
+ * only on the Thread root bundle. Import also accepts legacy reply-level
+ * entries and folds them into the root without losing metadata.
  */
 export interface HugoCollectionRef {
   slug: string;
@@ -110,11 +111,20 @@ export interface HugoFrontMatter {
   rating?: number | null;
   featured_at?: string | null;
   pinned_at?: string | null;
+  /**
+   * Reply bundles only: the reply was published without announcing the Thread
+   * on Latest. Round-tripped so a restore rebuilds the same ordering.
+   */
+  quiet_reply?: boolean;
+
+  // Derived Featured Thread projection (root bundles only)
+  featured_post_ids?: string[];
+  featured_sort_at?: string;
 
   // Round-trip bookkeeping
   root_aliases?: string[];
 
-  // Memberships + attachments
+  // Thread memberships (root bundles only) + attachments
   collections?: HugoCollectionRef[];
   media?: JantMedia[];
 
@@ -201,6 +211,8 @@ const FRONT_MATTER_KEY_ORDER: readonly string[] = [
   "quote_text",
   "rating",
   "featured_at",
+  "featured_post_ids",
+  "featured_sort_at",
   "pinned_at",
 
   // Bookkeeping / attachments

package/src/lib/jant-branding.ts

@@ -23,6 +23,7 @@ import { toPublicPath } from "./url.js";
 
 export { JANT_APP_ICON_CORNER_RADIUS, JANT_LOGO_PATH_DATA, JANT_LOGO_VIEW_BOX };
 
+export const JANT_HOME_URL = "https://jant.me";
 export const JANT_REPO_URL = "https://github.com/jant-me/jant";
 export const HOME_BRANDING_PREFIX = "Build with";
 export const HOME_BRANDING_LINK_LABEL = "Jant";

package/src/lib/link-preview.ts

@@ -0,0 +1,25 @@
+const LINK_PREVIEW_PROVIDER_LABELS: Record<string, string> = {
+  youtube: "YouTube",
+  vimeo: "Vimeo",
+  bilibili: "Bilibili",
+};
+
+/**
+ * Return the display label for a recognized Link preview provider.
+ *
+ * @param provider - Stored provider identifier, such as `youtube`
+ * @returns A stable display label, or undefined for unknown providers
+ * @example
+ * ```ts
+ * getLinkPreviewProviderLabel("youtube"); // "YouTube"
+ * getLinkPreviewProviderLabel("unknown"); // undefined
+ * ```
+ */
+export function getLinkPreviewProviderLabel(
+  provider?: string,
+): string | undefined {
+  const normalizedProvider = provider?.trim().toLowerCase();
+  return normalizedProvider
+    ? LINK_PREVIEW_PROVIDER_LABELS[normalizedProvider]
+    : undefined;
+}