@jant/core 0.2.17 → 0.2.19

package/src/i18n/locales/zh-Hant.ts

@@ -1 +1 @@
-/*eslint-disable*/import type{Messages}from"@lingui/core";export const messages=JSON.parse("{\"+7Wr2a\":[\"編輯: \",[\"title\"]],\"+MACwa\":[\"尚未有任何收藏。\"],\"+owNNn\":[\"文章\"],\"+zy2Nq\":[\"類型\"],\"/0D1Xp\":[\"編輯收藏集\"],\"/Rj5P4\":[\"您的姓名\"],\"0JkyS7\":[\"建立您的第一個頁面\"],\"0a6MpL\":[\"新重定向\"],\"1CU1Td\":[\"網址安全識別碼（小寫、數字、連字符）\"],\"1DBGsz\":[\"筆記\"],\"2N0qpv\":[\"文章標題...\"],\"2q/Q7x\":[\"可見性\"],\"2rJGtU\":[\"頁面標題...\"],\"3Yvsaz\":[\"302（臨時）\"],\"4/SFQS\":[\"查看網站\"],\"40TVQj\":[\"自訂路徑（選填）\"],\"4KzVT6\":[\"刪除頁面\"],\"4b3oEV\":[\"內容\"],\"4mDPGp\":[\"此頁面的 URL 路徑。使用小寫字母、數字和連字符。\"],\"6WdDG7\":[\"頁面\"],\"7G4SBz\":[\"頁面內容（支持Markdown）...\"],\"7Mk+/h\":[\"更新收藏集\"],\"7Q1KKN\":[\"來源路徑\"],\"7nGhhM\":[\"你在想什麼？\"],\"7p5kLi\":[\"儀表板\"],\"8ZsakT\":[\"密碼\"],\"90Luob\":[[\"count\"],\" 條回覆\"],\"A1taO8\":[\"搜尋\"],\"AyHO4m\":[\"這個收藏是關於什麼的？\"],\"B373X+\":[\"編輯文章\"],\"B495Gs\":[\"檔案館\"],\"BjF0Jv\":[\"僅限小寫字母、數字和連字符\"],\"D9Oea+\":[\"永久鏈接\"],\"DHhJ7s\":[\"上一頁\"],\"DoJzLz\":[\"收藏夾\"],\"E80cJw\":[\"刪除此媒體將永久從存儲中移除它。\"],\"EEYbdt\":[\"發佈\"],\"EGwzOK\":[\"完成設置\"],\"EkH9pt\":[\"更新\"],\"FGrimz\":[\"新帖子\"],\"FkMol5\":[\"精選\"],\"Fxf4jq\":[\"描述（可選）\"],\"GA5A5H\":[\"刪除收藏夾\"],\"GorKul\":[\"歡迎來到 Jant\"],\"GrZ6fH\":[\"新頁面\"],\"HfyyXl\":[\"我的部落格\"],\"HiETwV\":[\"安靜（正常）\"],\"Hzi9AA\":[\"未找到任何帖子。\"],\"I6gXOa\":[\"路徑\"],\"IagCbF\":[\"網址\"],\"J4FNfC\":[\"此集合中沒有帖子。\"],\"JIBC/T\":[\"支援的格式：JPEG、PNG、GIF、WebP、SVG。最大大小：10MB。\"],\"JiP4aa\":[\"已發佈的頁面可以通過其路徑訪問。草稿不可見。\"],\"K9NcLu\":[\"使用此 URL 將媒體嵌入到您的帖子中。\"],\"KiJn9B\":[\"備註\"],\"L85WcV\":[\"縮略名\"],\"LkvLQe\":[\"尚未有頁面。\"],\"M8kJqa\":[\"草稿\"],\"M9xgHy\":[\"重定向\"],\"MHrjPM\":[\"標題\"],\"MZbQHL\":[\"未找到結果。\"],\"Mhf/H/\":[\"建立重定向\"],\"MqghUt\":[\"搜尋帖子...\"],\"N40H+G\":[\"所有\"],\"O3oNi5\":[\"電子郵件\"],\"OCNZaU\":[\"重定向來源的路徑\"],\"ODiSoW\":[\"尚未有帖子。\"],\"ONWvwQ\":[\"上傳\"],\"Pbm2/N\":[\"創建收藏夾\"],\"RDjuBN\":[\"設置\"],\"Rj01Fz\":[\"連結\"],\"RwGhWy\":[\"包含 \",[\"count\"],\" 則帖子的主題\"],\"SJmfuf\":[\"網站名稱\"],\"ST+lN2\":[\"尚未上傳任何媒體。\"],\"Tt5T6+\":[\"文章\"],\"TxE+Mj\":[\"1 條回覆\"],\"Tz0i8g\":[\"設定\"],\"U5v6Gh\":[\"編輯頁面\"],\"UDMjsP\":[\"快速操作\"],\"UGT5vp\":[\"保存設定\"],\"VUSy8D\":[\"搜尋失敗。請再試一次。\"],\"WDcQq9\":[\"不公開\"],\"Weq9zb\":[\"一般設定\"],\"WmZ/rP\":[\"到路徑\"],\"Y+7JGK\":[\"創建頁面\"],\"ZQKLI1\":[\"危險區域\"],\"ZhhOwV\":[\"引用\"],\"an5hVd\":[\"圖片\"],\"b+/jO6\":[\"301（永久）\"],\"bHYIks\":[\"登出\"],\"biOepV\":[\"← 返回首頁\"],\"cnGeoo\":[\"刪除\"],\"dEgA5A\":[\"取消\"],\"e6Jr7Q\":[\"← 返回收藏夾\"],\"ePK91l\":[\"編輯\"],\"eWLklq\":[\"引用\"],\"eneWvv\":[\"草稿\"],\"f6e0Ry\":[\"文章\"],\"fG7BxZ\":[\"透過 API 上傳圖片：POST /api/upload，並使用文件表單字段。\"],\"fttd2R\":[\"我的收藏\"],\"hG89Ed\":[\"圖片\"],\"hXzOVo\":[\"下一頁\"],\"he3ygx\":[\"複製\"],\"iH8pgl\":[\"返回\"],\"ig4hg2\":[\"讓我們設置您的網站。\"],\"jpctdh\":[\"查看\"],\"mTOYla\":[\"查看所有文章 →\"],\"n1ekoW\":[\"登入\"],\"oYPBa0\":[\"更新頁面\"],\"pRhYH2\":[\"收藏中的帖子 (\",[\"count\"],\")\"],\"qMyM2u\":[\"來源網址（選填）\"],\"r1MpXi\":[\"安靜\"],\"rdUucN\":[\"預覽\"],\"rzNUSl\":[\"包含 1 則貼文的主題\"],\"sGajR7\":[\"線程開始\"],\"t/YqKh\":[\"移除\"],\"tfrt7B\":[\"未配置任何重定向。\"],\"tiq7kl\":[\"頁面 \",[\"page\"]],\"u2f7vd\":[\"網站描述\"],\"u3wRF+\":[\"已發佈\"],\"u6Hp4N\":[\"Markdown\"],\"uAQUqI\":[\"狀態\"],\"vXIe7J\":[\"語言\"],\"vzU4k9\":[\"新收藏集\"],\"wEF6Ix\":[\"目的地路徑或 URL\"],\"wK4OTM\":[\"標題（選填）\"],\"wM5UXj\":[\"刪除媒體\"],\"wRR604\":[\"頁面\"],\"wja8aL\":[\"無標題\"],\"x0mzE0\":[\"創建你的第一篇帖子\"],\"x4RuFo\":[\"回到首頁\"],\"xYilR2\":[\"媒體\"],\"y28hnO\":[\"文章\"],\"yQ2kGp\":[\"載入更多\"],\"yzF66j\":[\"連結\"],\"z8ajIE\":[\"找到 1 個結果\"],\"zH6KqE\":[\"找到 \",[\"count\"],\" 個結果\"]}")as Messages;
+/*eslint-disable*/import type{Messages}from"@lingui/core";export const messages=JSON.parse("{\"+7Wr2a\":[\"Edit: \",[\"title\"]],\"+MACwa\":[\"尚未有任何收藏。\"],\"+owNNn\":[\"文章\"],\"+zy2Nq\":[\"類型\"],\"/0D1Xp\":[\"編輯收藏集\"],\"/Rj5P4\":[\"您的姓名\"],\"07Epll\":[\"這將為您的網站和儀表板設置主題。所有顏色主題都支持深色模式。\"],\"0JkyS7\":[\"建立您的第一個頁面\"],\"0a6MpL\":[\"新重定向\"],\"1CU1Td\":[\"網址安全識別碼（小寫、數字、連字符）\"],\"1DBGsz\":[\"筆記\"],\"2N0qpv\":[\"文章標題...\"],\"2q/Q7x\":[\"可見性\"],\"2rJGtU\":[\"頁面標題...\"],\"3Yvsaz\":[\"302（臨時）\"],\"4/SFQS\":[\"查看網站\"],\"40TVQj\":[\"自訂路徑（選填）\"],\"4KzVT6\":[\"刪除頁面\"],\"4b3oEV\":[\"內容\"],\"4mDPGp\":[\"此頁面的 URL 路徑。使用小寫字母、數字和連字符。\"],\"6WdDG7\":[\"頁面\"],\"7G4SBz\":[\"頁面內容（支持Markdown）...\"],\"7Mk+/h\":[\"更新收藏集\"],\"7Q1KKN\":[\"來源路徑\"],\"7aECQB\":[\"無效或已過期的連結\"],\"7nGhhM\":[\"你在想什麼？\"],\"7p5kLi\":[\"儀表板\"],\"7vhWI8\":[\"新密碼\"],\"8ZsakT\":[\"密碼\"],\"90Luob\":[[\"count\"],\" 條回覆\"],\"A1taO8\":[\"搜尋\"],\"AyHO4m\":[\"這個收藏是關於什麼的？\"],\"B373X+\":[\"編輯文章\"],\"B495Gs\":[\"檔案館\"],\"BjF0Jv\":[\"僅限小寫字母、數字和連字符\"],\"D9Oea+\":[\"永久鏈接\"],\"DCKkhU\":[\"當前密碼\"],\"DHhJ7s\":[\"上一頁\"],\"DoJzLz\":[\"收藏夾\"],\"E80cJw\":[\"刪除此媒體將永久從存儲中移除它。\"],\"EEYbdt\":[\"發佈\"],\"EGwzOK\":[\"完成設置\"],\"EkH9pt\":[\"更新\"],\"FGrimz\":[\"新帖子\"],\"FkMol5\":[\"精選\"],\"Fxf4jq\":[\"描述（可選）\"],\"GA5A5H\":[\"刪除收藏夾\"],\"GX2VMa\":[\"建立您的管理員帳戶。\"],\"GbVAnd\":[\"此密碼重設連結無效或已過期。請生成一個新的連結。\"],\"GorKul\":[\"歡迎來到 Jant\"],\"GrZ6fH\":[\"新頁面\"],\"GxkJXS\":[\"上傳中...\"],\"HfyyXl\":[\"My Blog\"],\"HiETwV\":[\"安靜（正常）\"],\"Hzi9AA\":[\"未找到任何帖子。\"],\"I6gXOa\":[\"路徑\"],\"IagCbF\":[\"網址\"],\"J4FNfC\":[\"此集合中沒有帖子。\"],\"JIBC/T\":[\"Supported formats: JPEG, PNG, GIF, WebP, SVG. Max size: 10MB.\"],\"Jed1wB\":[\"需要幫助嗎？請訪問<0>文檔</0>。\"],\"JiP4aa\":[\"已發佈的頁面可以通過其路徑訪問。草稿不可見。\"],\"K9NcLu\":[\"使用此 URL 將媒體嵌入到您的帖子中。\"],\"KbS2K9\":[\"重設密碼\"],\"KiJn9B\":[\"備註\"],\"L85WcV\":[\"縮略名\"],\"LkvLQe\":[\"尚未有頁面。\"],\"M1RvTd\":[\"點擊圖片以查看完整大小\"],\"M8kJqa\":[\"草稿\"],\"M9xgHy\":[\"重定向\"],\"MHrjPM\":[\"標題\"],\"MZbQHL\":[\"未找到結果。\"],\"Mhf/H/\":[\"建立重定向\"],\"MqghUt\":[\"搜尋帖子...\"],\"N40H+G\":[\"所有\"],\"O3oNi5\":[\"電子郵件\"],\"OCNZaU\":[\"重定向來源的路徑\"],\"ODiSoW\":[\"尚未有帖子。\"],\"ONWvwQ\":[\"上傳\"],\"Pbm2/N\":[\"創建收藏夾\"],\"RDjuBN\":[\"Setup\"],\"Rj01Fz\":[\"連結\"],\"RwGhWy\":[\"包含 \",[\"count\"],\" 則帖子的主題\"],\"SJmfuf\":[\"網站名稱\"],\"ST+lN2\":[\"尚未上傳任何媒體。\"],\"Tt5T6+\":[\"文章\"],\"TxE+Mj\":[\"1 條回覆\"],\"Tz0i8g\":[\"設定\"],\"U5v6Gh\":[\"編輯頁面\"],\"UDMjsP\":[\"快速操作\"],\"UGT5vp\":[\"保存設定\"],\"VUSy8D\":[\"Search failed. Please try again.\"],\"VhMDMg\":[\"更改密碼\"],\"WDcQq9\":[\"不公開\"],\"Weq9zb\":[\"一般設定\"],\"WmZ/rP\":[\"到路徑\"],\"Y+7JGK\":[\"創建頁面\"],\"ZQKLI1\":[\"危險區域\"],\"ZhhOwV\":[\"引用\"],\"aAIQg2\":[\"外觀\"],\"an5hVd\":[\"圖片\"],\"b+/jO6\":[\"301（永久）\"],\"bHYIks\":[\"登出\"],\"biOepV\":[\"← 返回首頁\"],\"cnGeoo\":[\"刪除\"],\"dEgA5A\":[\"取消\"],\"e6Jr7Q\":[\"← 返回收藏夾\"],\"ePK91l\":[\"編輯\"],\"eWLklq\":[\"引用\"],\"eneWvv\":[\"草稿\"],\"er8+x7\":[\"示範帳戶已預填。只需點擊登入。\"],\"f6e0Ry\":[\"文章\"],\"fG7BxZ\":[\"Upload images via the API: POST /api/upload with a file form field.\"],\"fttd2R\":[\"我的收藏\"],\"hG89Ed\":[\"圖片\"],\"hWOZIv\":[\"請輸入您的新密碼。\"],\"hXzOVo\":[\"下一頁\"],\"he3ygx\":[\"複製\"],\"iH8pgl\":[\"返回\"],\"ig4hg2\":[\"Let's set up your site.\"],\"jpctdh\":[\"查看\"],\"k1ifdL\":[\"處理中...\"],\"mTOYla\":[\"查看所有文章 →\"],\"n1ekoW\":[\"登入\"],\"oYPBa0\":[\"更新頁面\"],\"p2/GCq\":[\"確認密碼\"],\"pRhYH2\":[\"收藏中的帖子 (\",[\"count\"],\")\"],\"pZq3aX\":[\"上傳失敗。請再試一次。\"],\"qMyM2u\":[\"來源網址（選填）\"],\"r1MpXi\":[\"安靜\"],\"rFmBG3\":[\"顏色主題\"],\"rdUucN\":[\"預覽\"],\"rzNUSl\":[\"包含 1 則貼文的主題\"],\"sGajR7\":[\"線程開始\"],\"t/YqKh\":[\"移除\"],\"tfrt7B\":[\"未配置任何重定向。\"],\"tiq7kl\":[\"頁面 \",[\"page\"]],\"u2f7vd\":[\"網站描述\"],\"u3wRF+\":[\"已發佈\"],\"u6Hp4N\":[\"Markdown\"],\"uAQUqI\":[\"狀態\"],\"vXIe7J\":[\"語言\"],\"vzU4k9\":[\"新收藏集\"],\"wEF6Ix\":[\"目的地路徑或 URL\"],\"wK4OTM\":[\"標題（選填）\"],\"wM5UXj\":[\"刪除媒體\"],\"wRR604\":[\"頁面\"],\"wja8aL\":[\"無標題\"],\"x+doid\":[\"圖片會自動優化：調整大小至最大 1920 像素，轉換為 WebP 格式，並去除元數據。\"],\"x0mzE0\":[\"創建你的第一篇帖子\"],\"x4RuFo\":[\"回到首頁\"],\"xYilR2\":[\"媒體\"],\"y28hnO\":[\"文章\"],\"yQ2kGp\":[\"載入更多\"],\"yjkELF\":[\"確認新密碼\"],\"yzF66j\":[\"連結\"],\"z8ajIE\":[\"找到 1 個結果\"],\"zH6KqE\":[\"找到 \",[\"count\"],\" 個結果\"]}")as Messages;

package/src/lib/config.ts

@@ -1,44 +1,94 @@
 /**
- * Unified Configuration Helpers
+ * Unified Configuration System
  *
- * Configuration priority: Environment Variables > Database > Default Values
+ * Provides a flexible configuration system with two priority modes:
+ * - User-configurable (envOnly: false): Database > Environment > Default
+ * - Environment-only (envOnly: true): Environment > Default
  *
- * This follows the 12-factor app methodology where configuration is stored
- * in environment variables, while allowing runtime overrides via database.
+ * All configuration fields are defined in CONFIG_FIELDS (types.ts).
  */
 
 import type { Context } from "hono";
+import { CONFIG_FIELDS, type ConfigKey } from "../types.js";
 
 /**
- * Get site name with fallback chain: ENV > DB > Default
+ * Get the fallback value for a config key (ENV > Default), skipping the database.
+ * Used for placeholder values in forms where the DB value is shown separately.
  *
  * @param c - Hono context
- * @returns Site name
+ * @param key - Configuration key from CONFIG_FIELDS
+ * @returns Fallback value from environment or default
  *
  * @example
  * ```typescript
- * const siteName = await getSiteName(c);
- * // Returns: c.env.SITE_NAME ?? (DB: SITE_NAME) ?? "Jant"
+ * const placeholder = getConfigFallback(c, "SITE_NAME");
+ * // Returns: c.env.SITE_NAME ?? "Jant"
  * ```
  */
-export async function getSiteName(c: Context): Promise<string> {
-  // 1. Check environment variable
-  if (c.env.SITE_NAME) {
-    return c.env.SITE_NAME;
+export function getConfigFallback(c: Context, key: ConfigKey): string {
+  const field = CONFIG_FIELDS[key];
+  const envValue = c.env[key as keyof typeof c.env];
+  if (envValue && typeof envValue === "string") return envValue;
+  return field.defaultValue;
+}
+
+/**
+ * Generic configuration getter that respects priority settings
+ *
+ * @param c - Hono context
+ * @param key - Configuration key from CONFIG_FIELDS
+ * @returns Configuration value following the defined priority
+ *
+ * @example
+ * ```typescript
+ * // For user-configurable configs (SITE_NAME):
+ * // Returns: (DB: SITE_NAME) ?? c.env.SITE_NAME ?? "Jant"
+ *
+ * // For environment-only configs (SITE_URL):
+ * // Returns: c.env.SITE_URL ?? ""
+ * ```
+ */
+export async function getConfig(c: Context, key: ConfigKey): Promise<string> {
+  const field = CONFIG_FIELDS[key];
+
+  if (!field.envOnly) {
+    // User-configurable: DB > ENV > Default
+    // 1. Check database setting first
+    const dbValue = await c.var.services.settings.get(key);
+    if (dbValue) {
+      return dbValue;
+    }
   }
 
-  // 2. Check database setting
-  const dbValue = await c.var.services.settings.get("SITE_NAME");
-  if (dbValue) {
-    return dbValue;
+  // ENV > Default
+  // 2. Check environment variable
+  const envValue = c.env[key as keyof typeof c.env];
+  if (envValue && typeof envValue === "string") {
+    return envValue;
   }
 
   // 3. Default value
-  return "Jant";
+  return field.defaultValue;
+}
+
+/**
+ * Get site name with fallback chain: DB > ENV > Default
+ *
+ * @param c - Hono context
+ * @returns Site name
+ *
+ * @example
+ * ```typescript
+ * const siteName = await getSiteName(c);
+ * // Returns: (DB: SITE_NAME) ?? c.env.SITE_NAME ?? "Jant"
+ * ```
+ */
+export async function getSiteName(c: Context): Promise<string> {
+  return getConfig(c, "SITE_NAME");
 }
 
 /**
- * Get site description with fallback chain: ENV > DB > Default
+ * Get site description with fallback chain: DB > ENV > Default
  *
  * @param c - Hono context
  * @returns Site description
@@ -46,27 +96,15 @@ export async function getSiteName(c: Context): Promise<string> {
  * @example
  * ```typescript
  * const description = await getSiteDescription(c);
- * // Returns: c.env.SITE_DESCRIPTION ?? (DB: SITE_DESCRIPTION) ?? "A microblog powered by Jant"
+ * // Returns: (DB: SITE_DESCRIPTION) ?? c.env.SITE_DESCRIPTION ?? "A microblog powered by Jant"
  * ```
  */
 export async function getSiteDescription(c: Context): Promise<string> {
-  // 1. Check environment variable
-  if (c.env.SITE_DESCRIPTION) {
-    return c.env.SITE_DESCRIPTION;
-  }
-
-  // 2. Check database setting
-  const dbValue = await c.var.services.settings.get("SITE_DESCRIPTION");
-  if (dbValue) {
-    return dbValue;
-  }
-
-  // 3. Default value
-  return "A microblog powered by Jant";
+  return getConfig(c, "SITE_DESCRIPTION");
 }
 
 /**
- * Get site language with fallback chain: ENV > DB > Default
+ * Get site language with fallback chain: DB > ENV > Default
  *
  * @param c - Hono context
  * @returns Site language code
@@ -74,21 +112,9 @@ export async function getSiteDescription(c: Context): Promise<string> {
  * @example
  * ```typescript
  * const lang = await getSiteLanguage(c);
- * // Returns: c.env.SITE_LANGUAGE ?? (DB: SITE_LANGUAGE) ?? "en"
+ * // Returns: (DB: SITE_LANGUAGE) ?? c.env.SITE_LANGUAGE ?? "en"
  * ```
  */
 export async function getSiteLanguage(c: Context): Promise<string> {
-  // 1. Check environment variable
-  if (c.env.SITE_LANGUAGE) {
-    return c.env.SITE_LANGUAGE;
-  }
-
-  // 2. Check database setting
-  const dbValue = await c.var.services.settings.get("SITE_LANGUAGE");
-  if (dbValue) {
-    return dbValue;
-  }
-
-  // 3. Default value
-  return "en";
+  return getConfig(c, "SITE_LANGUAGE");
 }

package/src/lib/constants.ts

@@ -21,11 +21,13 @@ export const RESERVED_PATHS = [
   "quotes",
   "media",
   "pages",
+  "reset",
   "p",
   "c",
   "static",
   "assets",
   "health",
+  "appearance",
 ] as const;
 
 export type ReservedPath = (typeof RESERVED_PATHS)[number];
@@ -52,6 +54,7 @@ export const SETTINGS_KEYS = {
   SITE_DESCRIPTION: "SITE_DESCRIPTION",
   SITE_LANGUAGE: "SITE_LANGUAGE",
   THEME: "THEME",
+  PASSWORD_RESET_TOKEN: "PASSWORD_RESET_TOKEN",
 } as const;
 
 export type SettingsKey = (typeof SETTINGS_KEYS)[keyof typeof SETTINGS_KEYS];

package/src/lib/image-processor.ts

@@ -217,10 +217,3 @@ async function processToFile(
 }
 
 export const ImageProcessor = { process, processToFile };
-
-// Expose globally for inline scripts
-if (typeof window !== "undefined") {
-  (
-    window as unknown as { ImageProcessor: typeof ImageProcessor }
-  ).ImageProcessor = ImageProcessor;
-}

package/src/lib/media-upload.ts

@@ -0,0 +1,148 @@
+/**
+ * Client-side Media Upload Handler
+ *
+ * Handles file upload flow:
+ * 1. User selects file via [data-media-upload] input
+ * 2. Creates placeholder in grid with spinner
+ * 3. Processes image via ImageProcessor (resize/convert to WebP)
+ * 4. Sets processed file on hidden Datastar form via DataTransfer API
+ * 5. Triggers form.requestSubmit() — Datastar handles upload + SSE response
+ */
+
+import { ImageProcessor } from "./image-processor.js";
+
+/**
+ * Format file size for display
+ */
+function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Ensure the media grid exists, removing empty state if needed
+ */
+function ensureGridExists(): HTMLElement {
+  let grid = document.getElementById("media-grid");
+  if (grid) return grid;
+
+  document.getElementById("empty-state")?.remove();
+
+  grid = document.createElement("div");
+  grid.id = "media-grid";
+  grid.className =
+    "grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5 gap-4";
+  document.getElementById("media-content")?.appendChild(grid);
+  return grid;
+}
+
+/**
+ * Create a placeholder card with spinner in the media grid
+ */
+function createPlaceholder(
+  fileName: string,
+  fileSize: number,
+  statusText: string,
+): HTMLElement {
+  const placeholder = document.createElement("div");
+  placeholder.id = "upload-placeholder";
+  placeholder.className = "group relative";
+  placeholder.innerHTML = `
+    <div class="aspect-square bg-muted rounded-lg overflow-hidden border flex items-center justify-center">
+      <div class="text-center px-2">
+        <svg class="animate-spin h-6 w-6 text-muted-foreground mx-auto mb-2" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+          <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+          <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+        </svg>
+        <span id="upload-status" class="text-xs text-muted-foreground">${statusText}</span>
+      </div>
+    </div>
+    <div class="mt-2 text-xs truncate" title="${fileName}">${fileName}</div>
+    <div class="text-xs text-muted-foreground">${formatFileSize(fileSize)}</div>
+  `;
+  return placeholder;
+}
+
+/**
+ * Replace placeholder content with an error message
+ */
+function showPlaceholderError(
+  placeholder: HTMLElement,
+  fileName: string,
+  errorMessage: string,
+): void {
+  placeholder.innerHTML = `
+    <div class="aspect-square bg-destructive/10 rounded-lg overflow-hidden border border-destructive flex items-center justify-center">
+      <div class="text-center px-2">
+        <span class="text-xs text-destructive">${errorMessage}</span>
+      </div>
+    </div>
+    <div class="mt-2 text-xs truncate text-destructive">${fileName}</div>
+    <button type="button" class="text-xs text-muted-foreground hover:underline" onclick="this.closest('.group').remove()">Remove</button>
+  `;
+}
+
+/**
+ * Handle the upload flow for a selected file
+ */
+async function handleUpload(
+  input: HTMLInputElement,
+  file: File,
+): Promise<void> {
+  const processingText = input.dataset.textProcessing || "Processing...";
+  const uploadingText = input.dataset.textUploading || "Uploading...";
+  const errorText =
+    input.dataset.textError || "Upload failed. Please try again.";
+
+  const grid = ensureGridExists();
+  const placeholder = createPlaceholder(file.name, file.size, processingText);
+  grid.prepend(placeholder);
+
+  try {
+    // Process image client-side (resize, convert to WebP)
+    const processed = await ImageProcessor.processToFile(file);
+
+    // Update status
+    const statusEl = document.getElementById("upload-status");
+    if (statusEl) statusEl.textContent = uploadingText;
+
+    // Set processed file on hidden form input via DataTransfer API
+    const formInput = document.getElementById(
+      "upload-file-input",
+    ) as HTMLInputElement | null;
+    const form = document.getElementById(
+      "upload-form",
+    ) as HTMLFormElement | null;
+    if (!formInput || !form) throw new Error("Upload form not found");
+
+    const dt = new DataTransfer();
+    dt.items.add(processed);
+    formInput.files = dt.files;
+
+    // Trigger Datastar-intercepted form submission
+    form.requestSubmit();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : errorText;
+    showPlaceholderError(placeholder, file.name, message);
+  }
+
+  // Reset file input so the same file can be re-selected
+  input.value = "";
+}
+
+/**
+ * Initialize media upload via event delegation
+ */
+function initMediaUpload(): void {
+  document.addEventListener("change", (e) => {
+    const input = (e.target as HTMLElement).closest(
+      "[data-media-upload]",
+    ) as HTMLInputElement | null;
+    if (!input?.files?.[0]) return;
+
+    handleUpload(input, input.files[0]);
+  });
+}
+
+initMediaUpload();

package/src/lib/sse.ts

@@ -1,20 +1,21 @@
 /**
- * Server-Sent Events (SSE) utilities for Datastar v1.0.0-RC.7
+ * Datastar response utilities for v1.0.0-RC.7
  *
- * Generates SSE events compatible with the Datastar client's expected format.
+ * Provides both SSE (multi-event) and plain HTTP (single-event) response helpers.
  *
- * @see https://data-star.dev/
+ * **Non-SSE helpers** (preferred for single operations):
+ * - `dsRedirect(url)` — redirect via text/html
+ * - `dsToast(message, type)` — toast notification via text/html
+ * - `dsSignals(signals)` — signal patch via application/json
  *
- * @example
- * ```ts
- * app.post("/api/example", (c) => {
- *   return sse(c, async (stream) => {
- *     await stream.patchSignals({ loading: false });
- *     await stream.patchElements('<div id="result">Done!</div>');
- *     await stream.redirect("/success");
- *   });
- * });
- * ```
+ * **SSE** (for multiple operations in one response):
+ * - `sse(c, handler)` — streaming SSE with full stream API
+ *
+ * Datastar auto-detects response type by Content-Type:
+ * - `text/html` → dispatches as `datastar-patch-elements`
+ * - `application/json` → dispatches as `datastar-patch-signals`
+ *
+ * @see https://data-star.dev/
  */
 
 import type { Context } from "hono";
@@ -106,8 +107,53 @@ export interface SSEStream {
    * ```
    */
   remove(selector: string): void;
+
+  /**
+   * Show a toast notification
+   *
+   * Appends a toast element to `#toast-container` with auto-dismiss after 3s.
+   *
+   * @param message - The message to display
+   * @param type - Toast type: "success" (default) or "error"
+   *
+   * @example
+   * ```ts
+   * await stream.toast("Settings saved successfully.");
+   * await stream.toast("Something went wrong.", "error");
+   * ```
+   */
+  toast(message: string, type?: "success" | "error"): void;
 }
 
+// ---------------------------------------------------------------------------
+// Shared internal helpers (used by both SSE and non-SSE response builders)
+// ---------------------------------------------------------------------------
+
+/** Build the redirect script tag for Datastar patch-elements */
+function buildRedirectScript(url: string): string {
+  const escapedUrl = url.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+  return `<script data-effect="el.remove()">window.location.href='${escapedUrl}'</script>`;
+}
+
+/** Build a toast notification HTML element */
+function buildToastHtml(message: string, type: "success" | "error"): string {
+  const cls = type === "error" ? "toast-error" : "toast-success";
+  const icon =
+    type === "error"
+      ? '<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor"><circle cx="12" cy="12" r="10"/><path d="m15 9-6 6M9 9l6 6"/></svg>'
+      : '<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor"><circle cx="12" cy="12" r="10"/><path d="m9 12 2 2 4-4"/></svg>';
+  const closeBtn = `<button class="toast-close" data-on:click="el.closest('.toast').classList.add('toast-out'); el.closest('.toast').addEventListener('animationend', () => el.closest('.toast').remove())"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor"><path d="M18 6 6 18M6 6l12 12"/></svg></button>`;
+  const escapedMessage = message
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+  return `<div class="toast ${cls}" data-init="setTimeout(() => { el.classList.add('toast-out'); el.addEventListener('animationend', () => el.remove()) }, 3000)">${icon}<span>${escapedMessage}</span>${closeBtn}</div>`;
+}
+
+// ---------------------------------------------------------------------------
+// SSE helpers
+// ---------------------------------------------------------------------------
+
 /**
  * Format a single SSE event string
  *
@@ -193,10 +239,8 @@ export function sse(
         },
 
         redirect(url) {
-          const escapedUrl = url.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-          const script = `<script data-effect="el.remove()">window.location.href='${escapedUrl}'</script>`;
           const dataLines: string[] = [
-            `elements ${script}`,
+            `elements ${buildRedirectScript(url)}`,
             "mode append",
             "selector body",
           ];
@@ -216,6 +260,17 @@ export function sse(
             ),
           );
         },
+
+        toast(message, type = "success") {
+          const dataLines: string[] = [
+            `elements ${buildToastHtml(message, type)}`,
+            "mode append",
+            "selector #toast-container",
+          ];
+          controller.enqueue(
+            encoder.encode(formatEvent("datastar-patch-elements", dataLines)),
+          );
+        },
       };
 
       await handler(stream);
@@ -232,3 +287,88 @@ export function sse(
 
   return new Response(body, { headers });
 }
+
+// ---------------------------------------------------------------------------
+// Non-SSE Datastar helpers (for single-operation responses)
+// ---------------------------------------------------------------------------
+
+/**
+ * Datastar redirect via text/html
+ *
+ * Returns a plain HTML response that Datastar dispatches as `datastar-patch-elements`.
+ * Use instead of `sse()` when the only action is a redirect.
+ *
+ * @param url - The URL to redirect to
+ * @param options - Optional extra headers (e.g. Set-Cookie for auth)
+ * @returns Response with text/html content-type
+ *
+ * @example
+ * ```ts
+ * return dsRedirect("/dash/posts");
+ *
+ * // With cookie forwarding (for auth)
+ * return dsRedirect("/dash", { headers: { "Set-Cookie": cookie } });
+ * ```
+ */
+export function dsRedirect(
+  url: string,
+  options?: { headers?: Record<string, string> },
+): Response {
+  return new Response(buildRedirectScript(url), {
+    headers: {
+      "Content-Type": "text/html",
+      "Datastar-Mode": "append",
+      "Datastar-Selector": "body",
+      ...options?.headers,
+    },
+  });
+}
+
+/**
+ * Datastar toast notification via text/html
+ *
+ * Returns a plain HTML response that Datastar dispatches as `datastar-patch-elements`.
+ * Use instead of `sse()` when the only action is showing a toast.
+ *
+ * @param message - The message to display
+ * @param type - Toast type: "success" (default) or "error"
+ * @returns Response with text/html content-type
+ *
+ * @example
+ * ```ts
+ * return dsToast("Settings saved successfully.");
+ * return dsToast("Something went wrong.", "error");
+ * ```
+ */
+export function dsToast(
+  message: string,
+  type: "success" | "error" = "success",
+): Response {
+  return new Response(buildToastHtml(message, type), {
+    headers: {
+      "Content-Type": "text/html",
+      "Datastar-Mode": "append",
+      "Datastar-Selector": "#toast-container",
+    },
+  });
+}
+
+/**
+ * Datastar signal patch via application/json
+ *
+ * Returns a JSON response that Datastar dispatches as `datastar-patch-signals`.
+ * Use instead of `sse()` when the only action is updating signals.
+ *
+ * @param signals - Object containing signal values to update
+ * @returns Response with application/json content-type
+ *
+ * @example
+ * ```ts
+ * return dsSignals({ _uploadError: "File too large" });
+ * ```
+ */
+export function dsSignals(signals: Record<string, unknown>): Response {
+  return new Response(JSON.stringify(signals), {
+    headers: { "Content-Type": "application/json" },
+  });
+}