@jant/core 0.3.25 → 0.3.26

package/src/lib/config.ts

@@ -118,3 +118,50 @@ export async function getSiteDescription(c: Context): Promise<string> {
 export async function getSiteLanguage(c: Context): Promise<string> {
   return getConfig(c, "SITE_LANGUAGE");
 }
+
+/**
+ * Get home default view with fallback chain: DB > ENV > Default
+ *
+ * @param c - Hono context
+ * @returns Home default view ("latest" or "featured")
+ *
+ * @example
+ * ```typescript
+ * const view = await getHomeDefaultView(c);
+ * // Returns: (DB: HOME_DEFAULT_VIEW) ?? "latest"
+ * ```
+ */
+export async function getHomeDefaultView(c: Context): Promise<string> {
+  return getConfig(c, "HOME_DEFAULT_VIEW");
+}
+
+/**
+ * Get timezone with fallback chain: DB > ENV > Default
+ *
+ * @param c - Hono context
+ * @returns Timezone string (e.g. "Beijing", "UTC")
+ */
+export async function getTimeZone(c: Context): Promise<string> {
+  return getConfig(c, "TIME_ZONE");
+}
+
+/**
+ * Get site footer markdown with fallback chain: DB > ENV > Default
+ *
+ * @param c - Hono context
+ * @returns Footer markdown string (empty string if not set)
+ */
+export async function getSiteFooter(c: Context): Promise<string> {
+  return getConfig(c, "SITE_FOOTER");
+}
+
+/**
+ * Check if search engine indexing is disabled
+ *
+ * @param c - Hono context
+ * @returns true if NOINDEX is set to "true"
+ */
+export async function isNoIndex(c: Context): Promise<boolean> {
+  const value = await getConfig(c, "NOINDEX");
+  return value === "true";
+}

package/src/lib/constants.ts

@@ -7,6 +7,7 @@
  */
 export const RESERVED_PATHS = [
   "featured",
+  "latest",
   "collections",
   "signin",
   "signout",
@@ -42,19 +43,26 @@ export function isReservedPath(path: string): boolean {
 export const DEFAULT_PAGE_SIZE = 100;
 
 /**
- * Settings keys (match environment variable naming)
+ * Settings keys - derived from CONFIG_FIELDS (Single Source of Truth)
+ *
+ * Only non-envOnly fields and internal fields are stored in DB settings.
+ * Environment-only fields (SITE_URL, AUTH_SECRET, etc.) are never in the DB.
  */
-export const SETTINGS_KEYS = {
-  ONBOARDING_STATUS: "ONBOARDING_STATUS",
-  SITE_NAME: "SITE_NAME",
-  SITE_DESCRIPTION: "SITE_DESCRIPTION",
-  SITE_LANGUAGE: "SITE_LANGUAGE",
-  THEME: "THEME",
-  CUSTOM_CSS: "CUSTOM_CSS",
-  PASSWORD_RESET_TOKEN: "PASSWORD_RESET_TOKEN",
-} as const;
+import { CONFIG_FIELDS, type ConfigKey } from "../types.js";
+
+type SettingsFieldKey = {
+  [K in ConfigKey]: (typeof CONFIG_FIELDS)[K] extends { envOnly: false }
+    ? K
+    : never;
+}[ConfigKey];
+
+export const SETTINGS_KEYS = Object.fromEntries(
+  Object.entries(CONFIG_FIELDS)
+    .filter(([, field]) => !field.envOnly || "internal" in field)
+    .map(([key]) => [key, key]),
+) as { [K in SettingsFieldKey]: K };
 
-export type SettingsKey = (typeof SETTINGS_KEYS)[keyof typeof SETTINGS_KEYS];
+export type SettingsKey = SettingsFieldKey;
 
 /**
  * Onboarding status values

package/src/lib/favicon.ts

@@ -0,0 +1,115 @@
+/**
+ * Favicon Utilities
+ *
+ * Sizes and ICO encoding for generated favicon variants.
+ * Favicon data is stored as base64 in the settings table (not R2)
+ * since the files are tiny and accessed on every page load.
+ */
+
+/**
+ * Favicon variant sizes (width x height in pixels)
+ */
+export const FAVICON_SIZES = {
+  ICO_16: 16,
+  ICO_32: 32,
+  APPLE_TOUCH: 180,
+} as const;
+
+/**
+ * Encode PNG images into an ICO file.
+ *
+ * ICO format (with PNG payloads):
+ * - Header: 6 bytes (reserved=0, type=1, count=N)
+ * - Directory: 16 bytes per entry (width, height, colors, reserved, planes, bpp, size, offset)
+ * - Data: raw PNG bytes for each entry
+ *
+ * @param entries - Array of { size, png } where png is an ArrayBuffer of PNG data
+ * @returns ICO file as a Blob
+ *
+ * @example
+ * ```ts
+ * const ico = encodeIco([
+ *   { size: 16, png: png16ArrayBuffer },
+ *   { size: 32, png: png32ArrayBuffer },
+ * ]);
+ * ```
+ */
+export function encodeIco(
+  entries: { size: number; png: ArrayBuffer }[],
+): Blob {
+  const headerSize = 6;
+  const dirEntrySize = 16;
+  const dirSize = entries.length * dirEntrySize;
+
+  let dataOffset = headerSize + dirSize;
+
+  // Build header + directory
+  const header = new ArrayBuffer(headerSize + dirSize);
+  const view = new DataView(header);
+
+  // ICO header
+  view.setUint16(0, 0, true); // reserved
+  view.setUint16(2, 1, true); // type = icon
+  view.setUint16(4, entries.length, true); // count
+
+  const pngBuffers: ArrayBuffer[] = [];
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i]!;
+    const offset = headerSize + i * dirEntrySize;
+
+    // Width/height: 0 means 256
+    view.setUint8(offset + 0, entry.size < 256 ? entry.size : 0);
+    view.setUint8(offset + 1, entry.size < 256 ? entry.size : 0);
+    view.setUint8(offset + 2, 0); // color count (0 for >256 colors)
+    view.setUint8(offset + 3, 0); // reserved
+    view.setUint16(offset + 4, 1, true); // color planes
+    view.setUint16(offset + 6, 32, true); // bits per pixel
+    view.setUint32(offset + 8, entry.png.byteLength, true); // image size
+    view.setUint32(offset + 12, dataOffset, true); // image offset
+
+    dataOffset += entry.png.byteLength;
+    pngBuffers.push(entry.png);
+  }
+
+  return new Blob([header, ...pngBuffers], { type: "image/x-icon" });
+}
+
+/**
+ * Convert an ArrayBuffer to a base64 string.
+ *
+ * @param buffer - The ArrayBuffer to encode
+ * @returns base64-encoded string
+ *
+ * @example
+ * ```ts
+ * const b64 = arrayBufferToBase64(await blob.arrayBuffer());
+ * ```
+ */
+export function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]!);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Convert a base64 string to a Uint8Array.
+ *
+ * @param base64 - The base64 string to decode
+ * @returns decoded Uint8Array
+ *
+ * @example
+ * ```ts
+ * const bytes = base64ToUint8Array(storedBase64);
+ * ```
+ */
+export function base64ToUint8Array(base64: string): Uint8Array {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}

package/src/lib/image.ts

@@ -102,36 +102,28 @@ export function getPublicUrlForProvider(
 }
 
 /**
- * Generates a media URL using UUIDv7-based paths.
+ * Generates a media URL from a storage key.
  *
- * Returns a public URL for a media file. If `publicUrl` is set, uses that directly
- * with the storage key. Otherwise, generates a `/media/{id}.{ext}` local proxy URL.
+ * Both proxy and CDN paths use the same structure — only the domain differs.
+ * Without a public URL, returns a root-relative path for the local proxy.
+ * With a public URL, prefixes that domain.
  *
- * @param mediaId - The UUIDv7 database ID of the media
- * @param storageKey - The storage object key (used to build CDN path and extract extension)
+ * @param storageKey - The storage object key (e.g. `"media/2025/01/uuid.webp"`)
  * @param publicUrl - Optional public URL base for direct CDN access
  * @returns The public URL for the media file
  *
  * @example
  * ```ts
- * // Without public URL - uses local proxy with UUID and extension
- * getMediaUrl("01902a9f-1a2b-7c3d", "media/2025/01/01902a9f-1a2b-7c3d.webp");
- * // Returns: "/media/01902a9f-1a2b-7c3d.webp"
+ * // Without public URL - local proxy
+ * getMediaUrl("media/2025/01/01902a9f-1a2b-7c3d.webp");
+ * // Returns: "/media/2025/01/01902a9f-1a2b-7c3d.webp"
  *
- * // With public URL - uses direct CDN
- * getMediaUrl("01902a9f-1a2b-7c3d", "media/2025/01/01902a9f-1a2b-7c3d.webp", "https://cdn.example.com");
+ * // With public URL - CDN
+ * getMediaUrl("media/2025/01/01902a9f-1a2b-7c3d.webp", "https://cdn.example.com");
  * // Returns: "https://cdn.example.com/media/2025/01/01902a9f-1a2b-7c3d.webp"
  * ```
  */
-export function getMediaUrl(
-  mediaId: string,
-  storageKey: string,
-  publicUrl?: string,
-): string {
-  if (publicUrl) {
-    return `${publicUrl.replace(/\/+$/, "")}/${storageKey}`;
-  }
-  // Extract extension from storage key
-  const ext = storageKey.split(".").pop() || "bin";
-  return `/media/${mediaId}.${ext}`;
+export function getMediaUrl(storageKey: string, publicUrl?: string): string {
+  const base = publicUrl ? publicUrl.replace(/\/+$/, "") : "";
+  return `${base}/${storageKey}`;
 }

package/src/lib/media-helpers.ts

@@ -45,9 +45,9 @@ export function buildMediaMap(
         );
         return {
           id: m.id,
-          url: getMediaUrl(m.id, m.storageKey, publicUrl),
+          url: getMediaUrl(m.storageKey, publicUrl),
           previewUrl: getImageUrl(
-            getMediaUrl(m.id, m.storageKey, publicUrl),
+            getMediaUrl(m.storageKey, publicUrl),
             imageTransformUrl,
             { width: 400, quality: 80, format: "auto", fit: "cover" },
           ),

package/src/lib/navigation.ts

@@ -5,9 +5,11 @@
  */
 
 import type { Context } from "hono";
-import { getSiteName } from "./config.js";
+import { getSiteName, getHomeDefaultView, getSiteFooter } from "./config.js";
 import type { Collection, NavItemView } from "../types.js";
 import { toNavItemViews } from "./view.js";
+import { getMediaUrl, getPublicUrlForProvider } from "./image.js";
+import { render as renderMarkdown } from "./markdown.js";
 
 /**
  * Navigation data needed by SiteLayout
@@ -19,6 +21,10 @@ export interface NavigationData {
   siteDescription: string;
   isAuthenticated: boolean;
   collections: Collection[];
+  homeDefaultView: string;
+  siteAvatarUrl?: string;
+  showHeaderAvatar?: boolean;
+  siteFooterHtml?: string;
 }
 
 /**
@@ -43,7 +49,11 @@ export interface NavigationData {
 export async function getNavigationData(c: Context): Promise<NavigationData> {
   const items = await c.var.services.navItems.list();
   const currentPath = new URL(c.req.url).pathname;
-  const siteName = await getSiteName(c);
+  const [siteName, homeDefaultView, siteFooter] = await Promise.all([
+    getSiteName(c),
+    getHomeDefaultView(c),
+    getSiteFooter(c),
+  ]);
 
   // Only include description if explicitly set (DB or env), not the default
   const dbDescription = await c.var.services.settings.get("SITE_DESCRIPTION");
@@ -51,6 +61,23 @@ export async function getNavigationData(c: Context): Promise<NavigationData> {
   const siteDescription =
     dbDescription || (typeof envDescription === "string" ? envDescription : "");
 
+  // Resolve avatar URL from storage key
+  const avatarKey = await c.var.services.settings.get("SITE_AVATAR");
+  const showHeaderAvatar =
+    (await c.var.services.settings.get("SHOW_HEADER_AVATAR")) === "true";
+  let siteAvatarUrl: string | undefined;
+  if (avatarKey) {
+    const publicUrl = getPublicUrlForProvider(
+      c.env.STORAGE_DRIVER || "r2",
+      c.env.R2_PUBLIC_URL,
+      c.env.S3_PUBLIC_URL,
+    );
+    siteAvatarUrl = getMediaUrl(avatarKey, publicUrl);
+  }
+
+  // Render footer markdown
+  const siteFooterHtml = siteFooter ? renderMarkdown(siteFooter) : undefined;
+
   const links = toNavItemViews(items, currentPath);
 
   // Check auth status for compose button
@@ -79,5 +106,9 @@ export async function getNavigationData(c: Context): Promise<NavigationData> {
     siteDescription,
     isAuthenticated,
     collections,
+    homeDefaultView,
+    siteAvatarUrl,
+    showHeaderAvatar: showHeaderAvatar && !!siteAvatarUrl,
+    siteFooterHtml,
   };
 }

package/src/lib/render.tsx

@@ -50,10 +50,24 @@ export function renderPublicPage(c: Context, options: RenderPublicPageOptions) {
     currentPath: navData.currentPath,
     isAuthenticated: navData.isAuthenticated,
     collections: navData.collections,
+    homeDefaultView: navData.homeDefaultView,
+    siteAvatarUrl: navData.siteAvatarUrl,
+    showHeaderAvatar: navData.showHeaderAvatar,
+    siteFooterHtml: navData.siteFooterHtml,
   };
 
+  // Read favicon and noindex from context (set by theme middleware)
+  const faviconUrl = c.get("faviconUrl") as string | undefined;
+  const noindex = c.get("noindex") as boolean | undefined;
+
   return c.html(
-    <BaseLayout title={title} description={description} c={c}>
+    <BaseLayout
+      title={title}
+      description={description}
+      c={c}
+      faviconUrl={faviconUrl}
+      noindex={noindex}
+    >
       <SiteLayout {...layoutProps}>{content}</SiteLayout>
     </BaseLayout>,
   );

package/src/lib/schemas.ts

@@ -153,6 +153,45 @@ export const CreateCollectionSchema = z.object({
  */
 export const UpdateCollectionSchema = CreateCollectionSchema.partial();
 
+// =============================================================================
+// Auth Schemas
+// =============================================================================
+
+/**
+ * Setup form validation schema
+ */
+export const SetupSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  email: z.string().email("Invalid email address"),
+  password: z.string().min(8, "Password must be at least 8 characters"),
+});
+
+/**
+ * Sign-in form validation schema
+ */
+export const SigninSchema = z.object({
+  email: z.string().email("Invalid email address"),
+  password: z.string().min(1, "Password is required"),
+});
+
+/**
+ * Password reset form validation schema
+ */
+export const ResetPasswordSchema = z
+  .object({
+    password: z.string().min(8, "Password must be at least 8 characters"),
+    confirmPassword: z.string().min(1),
+    token: z.string().min(1),
+  })
+  .refine((d) => d.password === d.confirmPassword, {
+    message: "Passwords do not match",
+    path: ["confirmPassword"],
+  });
+
+// =============================================================================
+// Form Data Helpers
+// =============================================================================
+
 /**
  * Form data helper: safely parse a FormData value with a schema
  *