@jant/core 0.6.16 → 0.7.1

package/src/lib/startup-config.ts

@@ -1,4 +1,5 @@
 import { escapeHtml } from "./html.js";
+import { getJantDocsUrl } from "./jant-docs.js";
 import {
   getAuthSecret,
   getHostedControlPlaneBaseUrl,
@@ -94,8 +95,7 @@ function getAuthSecretErrorHtml(kind: AuthSecretIssueKind): string {
   return renderConfigurationErrorPage({
     title: titleByKind[kind],
     bodyHtml: `${leadByKind[kind]}${runtimeInstructions}`,
-    docsHref:
-      "https://github.com/jant-me/jant/blob/main/docs/configuration.md#required",
+    docsHref: getJantDocsUrl("configuration#required"),
   });
 }
 
@@ -219,8 +219,7 @@ function getHostBasedConfigurationErrorHtml(
   return renderConfigurationErrorPage({
     title: "Hosted configuration is incomplete",
     bodyHtml: `<p>Jant is running with <code>SITE_RESOLUTION_MODE=host-based</code>, so hosted control-plane integration must be configured before the instance can serve requests.</p><ul>${itemsHtml}</ul>`,
-    docsHref:
-      "https://github.com/jant-me/jant/blob/main/docs/configuration.md#hosted-control-plane-integration-variables",
+    docsHref: getJantDocsUrl("configuration"),
   });
 }
 
@@ -243,8 +242,7 @@ export function getRuntimeConfigurationErrorPage(message: string): string {
   return renderConfigurationErrorPage({
     title: "Configuration Error",
     bodyHtml: `<p>${escapeHtml(message)}</p><p>Update your environment or instance data, then restart Jant.</p>`,
-    docsHref:
-      "https://github.com/jant-me/jant/blob/main/docs/configuration.md#site-resolution",
+    docsHref: getJantDocsUrl("configuration"),
   });
 }
 

package/src/lib/storage.ts

@@ -432,6 +432,13 @@ export function createS3Driver(config: S3DriverConfig): StorageDriver {
           // uploaded object checksums during finalize, so only enable response
           // checksum verification when a request explicitly asks for it.
           responseChecksumValidation: "WHEN_REQUIRED",
+          // Presigning runs with an empty body, so the SDK's default
+          // "WHEN_SUPPORTED" request checksums bake CRC32-of-nothing
+          // (x-amz-checksum-crc32=AAAAAA==) into every presigned PUT URL. The
+          // browser then uploads real bytes and the storage provider rejects
+          // the mismatch. Only send a request checksum when the caller asked
+          // for one (presignPut passes ChecksumSHA256 explicitly).
+          requestChecksumCalculation: "WHEN_REQUIRED",
         });
         return {
           send: (cmd: unknown) => client.send(cmd as never),

package/src/lib/summary.ts

@@ -22,6 +22,21 @@ interface TiptapNode {
   attrs?: Record<string, unknown>;
 }
 
+/**
+ * Summary limits for titled, article-style posts — the excerpt is a teaser
+ * and the reader continues on the post's own page.
+ */
+export const ARTICLE_SUMMARY_MAX_BLOCKS = 5;
+export const ARTICLE_SUMMARY_MAX_CHARS = 500;
+/**
+ * Larger limits for untitled notes — the body itself is the content, so the
+ * preview only exists to cap runaway length.
+ */
+export const NOTE_SUMMARY_MAX_BLOCKS = 10;
+export const NOTE_SUMMARY_MAX_CHARS = 1500;
+/** Don't truncate an untitled note just to hide a tail under this many chars. */
+export const NOTE_SUMMARY_MIN_HIDDEN_CHARS = 200;
+
 /**
  * Block node types that carry user-visible content for summary extraction.
  * Structural nodes (horizontalRule, moreBreak, image) are excluded.
@@ -348,3 +363,38 @@ export function extractSummaryHtml(
     breakAtIndex: lastSelectedIdx + 1,
   };
 }
+
+/**
+ * Extract the summary the site's timeline shows for a post, at the boundary
+ * the timeline uses.
+ *
+ * Wraps {@link extractSummaryHtml} with the limits that decide where a card
+ * stops: a titled post is an article whose excerpt is a teaser, an untitled one
+ * is a note whose body is the content and only needs a cap. Callers that need
+ * that boundary — the feed renderer, the theme exporter — share this rather
+ * than repeating five numbers each.
+ *
+ * @param bodyJson - TipTap JSON body, or null/undefined for a post without one
+ * @param hasTitle - Whether the post has a title, which makes it an article
+ * @param renderOptions - Renderer options, notably the footnote namespace
+ * @returns The truncated HTML and whether content continues, or null when
+ *   there is no TipTap document to truncate
+ * @example
+ * extractTimelineSummary(post.body, !!post.title, { namespace: post.id });
+ * // { html: "<p>Intro</p>", hasMore: true }
+ */
+export function extractTimelineSummary(
+  bodyJson: string | null | undefined,
+  hasTitle: boolean,
+  renderOptions: TiptapRenderOptions = {},
+): { html: string; hasMore: boolean } | null {
+  if (!bodyJson) return null;
+  const result = extractSummaryHtml(
+    bodyJson,
+    hasTitle ? ARTICLE_SUMMARY_MAX_BLOCKS : NOTE_SUMMARY_MAX_BLOCKS,
+    hasTitle ? ARTICLE_SUMMARY_MAX_CHARS : NOTE_SUMMARY_MAX_CHARS,
+    hasTitle ? 0 : NOTE_SUMMARY_MIN_HIDDEN_CHARS,
+    renderOptions,
+  );
+  return result ? { html: result.html, hasMore: result.hasMore } : null;
+}

package/src/lib/thread-fold.ts

@@ -0,0 +1,161 @@
+/**
+ * Thread Fold
+ *
+ * How much of a thread the timeline shows, and how much it folds away.
+ *
+ * A thread appears in two places that cannot select its posts the same way.
+ * The site paints a page of timeline items and must not load whole threads to
+ * do it, so `getThreadTimelineContext` ranks replies in SQL and hands the
+ * buckets down. The feed already holds every reply — `<content>` carries the
+ * whole chain — so it slices the array it has. Two access paths, one rule.
+ *
+ * This module owns what they share: the thresholds, and the arithmetic that
+ * turns a selection into a hidden count. Whoever changes the shape of the fold
+ * changes it here, and both surfaces move together.
+ *
+ * ## The fold
+ *
+ * ```
+ * root · reply 1 · reply 2 · [N more posts] · 3rd-newest · 2nd-newest · newest
+ * ```
+ *
+ * Six posts at most. A thread that fits arrives whole, with no gap at all —
+ * the gap appears only once something is actually left out.
+ *
+ * ## Where the gap points
+ *
+ * **At the first post it hides.** The link stands for a run of posts, and it
+ * opens the earliest of them, so a reader following "3 more posts" lands on
+ * the first of those three.
+ *
+ * It used to open the last *visible* post instead, on the reasoning that the
+ * detail page would then start just above the missing stretch, like a
+ * bookmark. That was a deliberate choice and it reads well on the site — but
+ * it makes the link mean something other than what its label says, and the
+ * feed cannot follow it: `<jant:thread>`'s `gap` attribute is documented as
+ * the first hidden post, and a consumer joining it against the `<jant:post>`
+ * rows would be handed a post that is on screen. One rule beats two, so both
+ * surfaces open the first hidden post.
+ */
+
+import type { Post, PostView } from "../types.js";
+
+/**
+ * Replies kept from the start of a thread, as context for the newest post.
+ *
+ * Also fixes where the SQL path's rank cut-off falls, so the two selections
+ * stay the same fold.
+ */
+export const THREAD_LEADING_REPLIES = 2;
+
+/**
+ * Replies kept from the end of a thread, the newest one included — it is the
+ * hero, and the two before it are its immediate context.
+ */
+export const THREAD_TRAILING_REPLIES = 3;
+
+/** Anything with an id, which is all the dedupe needs. */
+type Identified = Pick<Post, "id"> | Pick<PostView, "id">;
+
+/**
+ * How many replies a fold leaves unshown.
+ *
+ * Deduplicated, because on a short thread the buckets overlap: with four
+ * replies the first is also the third-newest, and counting it twice would
+ * report posts hidden that are on screen.
+ *
+ * @param selection - The replies the fold shows, and the thread's total
+ * @returns Replies the fold hides, never negative
+ * @example
+ * getThreadHiddenCount({ leadingReplies: [r1, r2], trailingReplies: [r6, r7],
+ *   latestReply: r8, totalReplyCount: 8 }); // 3
+ */
+export function getThreadHiddenCount({
+  leadingReplies,
+  trailingReplies,
+  latestReply,
+  totalReplyCount,
+}: {
+  leadingReplies: Identified[];
+  trailingReplies: Identified[];
+  latestReply: Identified;
+  totalReplyCount: number;
+}): number {
+  const shown = new Set(
+    [...leadingReplies, ...trailingReplies, latestReply].map((post) => post.id),
+  );
+  return Math.max(0, totalReplyCount - shown.size);
+}
+
+/** What the fold shows of a thread, and what it hides. */
+export interface ThreadFold<T> {
+  /** Earliest replies, kept as context above the gap. */
+  leadingReplies: T[];
+  /** Replies just before the newest, kept as its immediate context. */
+  trailingReplies: T[];
+  /** The newest reply — the hero the timeline builds the card around. */
+  latestReply: T;
+  /** First reply the fold hides, which is where the gap link points. */
+  firstHiddenReply: T | null;
+  /** How many replies the fold hides. */
+  hiddenCount: number;
+}
+
+/**
+ * Fold a thread whose replies are already in hand.
+ *
+ * Takes the same slices the SQL path ranks for: the first
+ * `THREAD_LEADING_REPLIES`, and the last `THREAD_TRAILING_REPLIES` with the
+ * newest as the hero. `getPublishedThreads` returns each Thread in Thread
+ * order, the same `threadOrder` the window functions rank by, so once the root
+ * is set aside position in this array *is* the rank — no approximation.
+ *
+ * @param replies - Every published reply, oldest first
+ * @returns The fold, or null when the thread has no replies
+ * @example
+ * foldThreadReplies([r1, r2, r3, r4, r5, r6, r7, r8]);
+ * // leading [r1, r2], trailing [r6, r7], latest r8, firstHidden r3, hidden 3
+ */
+export function foldThreadReplies<T extends Identified>(
+  replies: T[],
+): ThreadFold<T> | null {
+  const latestReply = replies.at(-1);
+  if (!latestReply) return null;
+
+  // A short thread's windows overlap, and the hero is inside both of them on
+  // the shortest ones: with a single reply, that reply is the newest *and* the
+  // whole leading window. Each list therefore drops whatever an earlier one
+  // already shows, hero first — the same order `ThreadPreview` dedupes in when
+  // it walks the buckets the SQL path hands it.
+  const leadingReplies = replies
+    .slice(0, THREAD_LEADING_REPLIES)
+    .filter((reply) => reply.id !== latestReply.id);
+
+  const leadingIds = new Set(leadingReplies.map((reply) => reply.id));
+  const trailingReplies = replies
+    .slice(-THREAD_TRAILING_REPLIES, -1)
+    .filter(
+      (reply) => reply.id !== latestReply.id && !leadingIds.has(reply.id),
+    );
+
+  const shown = new Set([
+    ...leadingIds,
+    ...trailingReplies.map((reply) => reply.id),
+    latestReply.id,
+  ]);
+
+  return {
+    leadingReplies,
+    trailingReplies,
+    latestReply,
+    // In thread order, so the gap link lands on the earliest post it stands
+    // for rather than somewhere in the middle of the run it hides.
+    firstHiddenReply: replies.find((reply) => !shown.has(reply.id)) ?? null,
+    hiddenCount: getThreadHiddenCount({
+      leadingReplies,
+      trailingReplies,
+      latestReply,
+      totalReplyCount: replies.length,
+    }),
+  };
+}

package/src/lib/time.ts

@@ -223,3 +223,35 @@ export function formatYearMonth(timestamp: number, timeZone = "UTC"): string {
   const month = parts.find((part) => part.type === "month")?.value ?? "01";
   return `${year}-${month}`;
 }
+
+/**
+ * Formats a "YYYY-MM" grouping key as a readable month label.
+ *
+ * The label is always en-US, matching the archive's other month copy — the
+ * grid header and the list marker read from this one function so their labels
+ * cannot drift apart.
+ *
+ * @param yearMonth - Year-month string in "YYYY-MM" format
+ * @returns Month label such as "February 2024", or null when the key is malformed
+ *
+ * @example
+ * ```ts
+ * const label = formatYearMonthLabel("2024-02");
+ * // Returns: "February 2024"
+ * ```
+ */
+export function formatYearMonthLabel(yearMonth: string): string | null {
+  const [year, month] = yearMonth.split("-");
+  if (!year || !month) return null;
+
+  const yearNumber = parseInt(year, 10);
+  const monthNumber = parseInt(month, 10);
+  if (!Number.isInteger(yearNumber) || !Number.isInteger(monthNumber)) {
+    return null;
+  }
+
+  return new Date(yearNumber, monthNumber - 1).toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "long",
+  });
+}

package/src/lib/timeline.ts

@@ -15,9 +15,24 @@ import type {
 import type { AppVariables } from "../types/app-context.js";
 import { buildMediaMap } from "./media-helpers.js";
 import { createMediaContext, resolveDraftTailId, toPostView } from "./view.js";
+import { getViewLang } from "./view-language.js";
+import { toPublicPath } from "./url.js";
 
 type Env = { Bindings: Bindings; Variables: AppVariables };
 
+/**
+ * Language filter for the view the request is being served in.
+ *
+ * Read from the context rather than passed in, so a caller cannot forget it
+ * and quietly leak another language's posts into a language view.
+ *
+ * @param c - Hono context
+ * @returns Canonical tag to filter on, or undefined on the root view
+ */
+function viewLangFilter(c: Context<Env>): string | undefined {
+  return getViewLang(c) ?? undefined;
+}
+
 /**
  * Result from assembling a timeline page.
  */
@@ -88,11 +103,15 @@ async function buildTimelineItems(
 
   // Batch load media for the bounded leading/trailing thread context.
   const contextPostIds = new Set<string>();
+  const gapPostIds = new Set<string>();
   for (const ctx of threadContexts.values()) {
     contextPostIds.add(ctx.latestReply.id);
     for (const reply of [...ctx.leadingReplies, ...ctx.trailingReplies]) {
       contextPostIds.add(reply.id);
     }
+    // The gap target is never rendered, so it needs no media or collections —
+    // only the alias that decides its address.
+    if (ctx.firstHiddenReply) gapPostIds.add(ctx.firstHiddenReply.id);
   }
   const [contextMediaMap, contextCollectionsMap, contextAliasesMap] =
     contextPostIds.size > 0
@@ -112,7 +131,12 @@ async function buildTimelineItems(
           c.var.services.collections.getCollectionsByPostIds([
             ...contextPostIds,
           ]),
-          c.var.services.paths.getPostAliases([...contextPostIds]),
+          // Gap targets ride along here and nowhere else: their address is
+          // all the gap link needs.
+          c.var.services.paths.getPostAliases([
+            ...contextPostIds,
+            ...gapPostIds,
+          ]),
         ])
       : [new Map(), new Map(), new Map<string, string[]>()];
 
@@ -178,6 +202,12 @@ async function buildTimelineItems(
           leadingReplies: leadingReplyViews,
           trailingReplies: trailingReplyViews,
           latestReply: latestReplyView,
+          gapHref: threadCtx.firstHiddenReply
+            ? toPublicPath(
+                `/${firstContextAlias(threadCtx.firstHiddenReply.id) ?? threadCtx.firstHiddenReply.slug}`,
+                mediaCtx.sitePathPrefix,
+              )
+            : undefined,
           totalReplyCount: threadCtx.totalReplyCount,
         },
       };
@@ -242,7 +272,7 @@ async function buildCuratedThreadItems(
 
   return orderedThreads.reduce<TimelineItemView[]>((items, thread) => {
     const rootEntry = thread.posts[0];
-    if (!rootEntry || rootEntry.position !== 0) {
+    if (!rootEntry || rootEntry.post.id !== rootEntry.post.threadId) {
       return items;
     }
 
@@ -344,18 +374,22 @@ export async function assembleTimeline(
   const excludePrivate = !(options?.isAuthenticated ?? false);
 
   // Count + list are independent — run in parallel
+  const lang = viewLangFilter(c);
+
   const [totalCount, posts] = await Promise.all([
     c.var.services.posts.count({
       status: "published",
       excludeReplies: true,
       excludeLatestHidden: true,
       excludePrivate,
+      lang,
     }),
     c.var.services.posts.list({
       status: "published",
       excludeReplies: true,
       excludeLatestHidden: true,
       excludePrivate,
+      lang,
       limit: pageSize,
       offset,
     }),
@@ -420,14 +454,18 @@ export async function assembleFeaturedTimeline(
   const offset = (page - 1) * pageSize;
   const excludePrivate = !(options?.isAuthenticated ?? false);
 
+  const lang = viewLangFilter(c);
+
   const [totalCount, rootIds] = await Promise.all([
     c.var.services.posts.countFeaturedThreadRoots({
       status: "published",
       excludePrivate,
+      lang,
     }),
     c.var.services.posts.listFeaturedThreadRootIds({
       status: "published",
       excludePrivate,
+      lang,
       limit: pageSize,
       offset,
     }),
@@ -482,6 +520,7 @@ export async function assembleCollectionTimeline(
   const page = Math.max(1, options.page ?? 1);
   const offset = (page - 1) * pageSize;
   const excludePrivate = !(options.isAuthenticated ?? false);
+  const lang = viewLangFilter(c);
 
   const [totalCount, rootIds] = await Promise.all([
     c.var.services.posts.countCollectionThreadRootsForCollections(
@@ -489,6 +528,7 @@ export async function assembleCollectionTimeline(
       {
         status: "published",
         excludePrivate,
+        lang,
       },
     ),
     c.var.services.posts.listCollectionThreadRootIdsForCollections(
@@ -496,6 +536,7 @@ export async function assembleCollectionTimeline(
       {
         status: "published",
         excludePrivate,
+        lang,
         sortOrder: options.sortOrder,
         limit: pageSize,
         offset,

package/src/lib/tiptap-render.ts

@@ -48,8 +48,7 @@ export interface TiptapRenderOptions {
 }
 
 export type TiptapRenderResult =
-  | { ok: true; html: string }
-  | { ok: false; error: string };
+  { ok: true; html: string } | { ok: false; error: string };
 
 interface FootnoteReferencePlan {
   definitionId: string;

package/src/lib/tiptap-to-markdown.ts

@@ -11,8 +11,14 @@ import { serializeMarkdownDocument } from "./markdown-manager.js";
 /**
  * Converts a Tiptap JSON document to a Markdown string.
  *
- * @param json - Tiptap JSON string or parsed document object
+ * Throws rather than returning an empty string: a caller writing the result
+ * somewhere (an export, a text attachment) would otherwise replace the
+ * content with nothing and say nothing.
+ *
+ * @param json - Tiptap JSON document string
  * @returns Markdown string
+ * @throws {SyntaxError} When `json` is not JSON
+ * @throws {Error} When the root node is not a `doc`
  *
  * @example
  * ```ts
@@ -21,11 +27,11 @@ import { serializeMarkdownDocument } from "./markdown-manager.js";
  * ```
  */
 export function tiptapJsonToMarkdown(json: string): string {
-  try {
-    const doc = JSON.parse(json) as JSONContent;
-    if (doc.type !== "doc") return "";
-    return serializeMarkdownDocument(doc).trimEnd();
-  } catch {
-    return "";
+  const doc = JSON.parse(json) as JSONContent;
+  if (doc.type !== "doc") {
+    throw new Error(
+      `A TipTap body's root must be a doc node, not ${JSON.stringify(doc.type)}.`,
+    );
   }
+  return serializeMarkdownDocument(doc).trimEnd();
 }

package/src/lib/upload.ts

@@ -4,7 +4,7 @@
  * Shared file validation and storage key generation for upload routes.
  */
 
-import type { MediaKind } from "../types/constants.js";
+import type { ContentDisposition, MediaKind } from "../types/constants.js";
 import { createEntityId } from "./ids.js";
 
 const MEDIA_ROOT_PREFIX = "media";
@@ -161,16 +161,6 @@ const MIME_CATEGORY_MAP = new Map<string, MediaCategory>([
   ...CODE_MIME_TYPES.map((t) => [t, "code" as const] as const),
 ]);
 
-/**
- * Accept string for file inputs. Accepts all file types.
- *
- * @example
- * ```ts
- * <input type="file" accept={UPLOAD_ACCEPT} />
- * ```
- */
-export const UPLOAD_ACCEPT = "*/*";
-
 export type MediaCategory =
   | "image"
   | "video"
@@ -183,7 +173,7 @@ export type MediaCategory =
   | "3d"
   | "code";
 
-export type UploadContentDisposition = "inline" | "attachment";
+export type UploadContentDisposition = ContentDisposition;
 
 export interface StoredUploadPolicy {
   contentDisposition: UploadContentDisposition;
@@ -326,10 +316,22 @@ export function imageExtensionForMimeType(contentType: string): string | null {
   return IMAGE_MIME_EXTENSIONS[contentType] ?? null;
 }
 
+/** ISO BMFF `ftyp` major brands that mean a HEIC/HEIF still image. */
+const HEIC_FTYP_BRANDS = new Set([
+  "heic",
+  "heix",
+  "hevc",
+  "hevx",
+  "mif1",
+  "msf1",
+]);
+
 /**
  * Identify an image format from its leading bytes (magic numbers), so a remote
  * sideload can trust the actual content rather than the server's content-type
- * header. Recognizes every {@link isAllowedSideloadImageType} format.
+ * header. Recognizes every {@link isAllowedSideloadImageType} format, plus
+ * HEIC/HEIF — which no browser decodes natively and no sideload accepts, but
+ * which the composer converts before upload once it knows what it holds.
  *
  * @param bytes - The leading bytes of the file (≥ ~256 bytes recommended)
  * @returns The detected image MIME type, or null if unrecognized
@@ -367,6 +369,7 @@ export function sniffImageMimeType(bytes: Uint8Array): string | null {
   if (bytes.length >= 12 && readAscii(bytes, 4, 4) === "ftyp") {
     const brand = readAscii(bytes, 8, 4);
     if (brand === "avif" || brand === "avis") return "image/avif";
+    if (HEIC_FTYP_BRANDS.has(brand)) return "image/heic";
   }
   if (bytes.length >= 2 && bytes[0] === 0x42 && bytes[1] === 0x4d) {
     return "image/bmp";