@jant/core 0.6.16 → 0.7.1

package/src/lib/github-sync-repo-name.ts

@@ -0,0 +1,45 @@
+/**
+ * The repository name Jant proposes for a site's GitHub Sync mirror.
+ *
+ * The settings page prefills it on github.com/new, and a site export with no
+ * repository behind it uses it as the Worker name in `wrangler.jsonc`.
+ * Cloudflare names a Worker imported from a repository after the repository,
+ * so an export and a repository created with the default name agree without
+ * anyone editing either.
+ */
+
+/** Used when the site URL yields no host label. */
+const FALLBACK_REPO_NAME = "jant-site-sync";
+
+/**
+ * Derive the default repository name for a site's sync mirror.
+ *
+ * Uses the first DNS label of the site's host — a stable, URL-safe
+ * identifier tied to this Jant instance. A leading `www` is skipped: it
+ * names nothing about the site, and every `www.` site would otherwise
+ * propose the same `www-jant-sync`. It is kept when only a top-level domain
+ * follows it, since that label would say even less. The `-jant-sync` suffix
+ * tells the sync mirror apart from a user's own `{slug}-jant` source repo.
+ *
+ * @param siteUrl - The site's public URL.
+ * @returns A GitHub-safe repository name; `jant-site-sync` when the URL has
+ *   no usable host.
+ * @example
+ * suggestSyncRepoName("https://notes.example.com"); // "notes-jant-sync"
+ * suggestSyncRepoName("https://www.example.com"); // "example-jant-sync"
+ */
+export function suggestSyncRepoName(siteUrl: string): string {
+  let labels: string[] = [];
+  try {
+    labels = new URL(siteUrl).host.split(".");
+  } catch {
+    /* fall through */
+  }
+  const [first = "", second = "", ...more] = labels;
+  const label = first === "www" && more.length > 0 ? second : first;
+  const slug = label
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug ? `${slug}-jant-sync` : FALLBACK_REPO_NAME;
+}

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

@@ -34,6 +34,24 @@ export interface HugoCollectionRef {
   pinned_at?: string | null;
 }
 
+/**
+ * A smart collection's conditions on its section page (`type:
+ * smart_collection`). The stored selection, with two changes of spelling:
+ * `collection` is one collection's slug rather than a list of IDs, and
+ * `media` is `any`, `none`, or a list of kinds. The theme's
+ * `smart-collection-members` partial evaluates it; an import recreates the
+ * smart collection from it.
+ */
+export interface HugoSmartCollectionSelection {
+  collection?: string;
+  format?: string;
+  title?: boolean;
+  year?: number;
+  media?: "any" | "none" | string[];
+  replies?: boolean;
+  visibility?: string;
+}
+
 /**
  * Jant media attachment descriptor. Stored flat inside the `media:` front-
  * matter array. `src` is either:
@@ -90,6 +108,12 @@ export interface HugoFrontMatter {
   id?: string;
   title?: string;
   date?: string;
+  /**
+   * When the post was created, written only when it differs from `date` (a
+   * published post dated before or after it was written). Restored on import
+   * so thread order and "last edited" survive a move.
+   */
+  created?: string;
   updated?: string;
   slug?: string;
   type?: string;
@@ -97,13 +121,31 @@ export interface HugoFrontMatter {
 
   // Hugo routing
   aliases?: string[];
+  /**
+   * Published root bundles only: the `<id>` Jant's feeds gave the Thread's
+   * entry — its permalink, absolute, with no trailing slash. The theme's feed
+   * writes it as the entry's `<id>` so readers don't show the post again after
+   * a move. Written by the export, never read by the import.
+   */
+  feed_id?: string;
   build?: HugoBuildOptions;
+  /**
+   * Reply bundles only: 1-based position in the Thread. Jant orders a Thread
+   * by creation time, then ID; replies written in the same second tie on
+   * `date`, so the theme and the importer order by this instead.
+   */
+  weight?: number;
 
   // Jant post payload (flat — no `extra` nesting)
   format?: string;
   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 +153,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.
@@ -128,6 +180,14 @@ export interface HugoFrontMatter {
   collections?: HugoCollectionRef[];
   media?: JantMedia[];
 
+  // Smart collection section pages
+  selection?: HugoSmartCollectionSelection;
+  /**
+   * `list` or `grid`; absent when the smart collection follows the site's
+   * archive layout. Not `layout`, which Hugo reads as a template name.
+   */
+  display_layout?: string;
+
   // Escape hatch for page-specific export metadata.
   [key: string]: unknown;
 }
@@ -198,6 +258,7 @@ const FRONT_MATTER_KEY_ORDER: readonly string[] = [
   "type",
   "draft",
   "aliases",
+  "feed_id",
   "build",
 
   // Post payload
@@ -205,6 +266,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/image.ts

@@ -34,7 +34,11 @@ export interface ImageOptions {
  * - Cloudinary
  * - Any service with similar URL-based transformation API
  *
- * @param originalUrl - The original image URL
+ * A root-relative source is written without its leading slash, the form the
+ * transformation service resolves against its own host. Kept, it would produce
+ * `…/width=200//media/abc123`, which Cloudflare cannot fetch (`err=9404`).
+ *
+ * @param originalUrl - The original image URL, absolute or root-relative
  * @param transformUrl - The base URL for transformations (e.g., `https://example.com/cdn-cgi/image`)
  * @param options - Transformation options (width, height, quality, format, fit)
  * @returns The transformed URL or original URL if transformations are not configured
@@ -45,9 +49,13 @@ export interface ImageOptions {
  * getImageUrl("/media/abc123", undefined, { width: 200 });
  * // Returns: "/media/abc123"
  *
- * // With transform URL - returns transformed
+ * // With transform URL and a root-relative source
  * getImageUrl("/media/abc123", "https://example.com/cdn-cgi/image", { width: 200, quality: 80 });
- * // Returns: "https://example.com/cdn-cgi/image/width=200,quality=80/https://example.com/media/abc123"
+ * // Returns: "https://example.com/cdn-cgi/image/width=200,quality=80/media/abc123"
+ *
+ * // With transform URL and an absolute source
+ * getImageUrl("https://cdn.example.com/media/abc123", "https://example.com/cdn-cgi/image", { width: 200 });
+ * // Returns: "https://example.com/cdn-cgi/image/width=200/https://cdn.example.com/media/abc123"
  * ```
  */
 export function getImageUrl(
@@ -70,7 +78,12 @@ export function getImageUrl(
     return originalUrl;
   }
 
-  return `${transformUrl}/${params.join(",")}/${originalUrl}`;
+  const base = transformUrl.replace(/\/+$/, "");
+  const source =
+    originalUrl.startsWith("/") && !originalUrl.startsWith("//")
+      ? originalUrl.slice(1)
+      : originalUrl;
+  return `${base}/${params.join(",")}/${source}`;
 }
 
 /**

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;
+}