@jant/core 0.2.18 → 0.2.20

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAG5B,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAc,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAGlD,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAwCvD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,MAAM,GAAE,UAAe,GAAG,GAAG,CA+qBtD"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAG5B,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAc,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAGlD,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAwCvD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,MAAM,GAAE,UAAe,GAAG,GAAG,CAyoBtD"}

package/dist/app.js

@@ -36,7 +36,7 @@ import { sitemapRoutes } from "./routes/feed/sitemap.js";
 import { requireAuth } from "./middleware/auth.js";
 // Layouts for auth pages
 import { BaseLayout } from "./theme/layouts/index.js";
-import { sse } from "./lib/sse.js";
+import { dsRedirect, dsToast } from "./lib/sse.js";
 import { getAvailableThemes, buildThemeStyle } from "./lib/theme.js";
 /**
  * Create a Jant application
@@ -247,19 +247,13 @@ import { getAvailableThemes, buildThemeStyle } from "./lib/theme.js";
         const body = await c.req.json();
         const { name, email, password } = body;
         if (!name || !email || !password) {
-            return sse(c, async (stream)=>{
-                await stream.toast("All fields are required", "error");
-            });
+            return dsToast("All fields are required", "error");
         }
         if (password.length < 8) {
-            return sse(c, async (stream)=>{
-                await stream.toast("Password must be at least 8 characters", "error");
-            });
+            return dsToast("Password must be at least 8 characters", "error");
         }
         if (!c.var.auth) {
-            return sse(c, async (stream)=>{
-                await stream.toast("AUTH_SECRET not configured", "error");
-            });
+            return dsToast("AUTH_SECRET not configured", "error");
         }
         try {
             const signUpResponse = await c.var.auth.api.signUpEmail({
@@ -270,20 +264,14 @@ import { getAvailableThemes, buildThemeStyle } from "./lib/theme.js";
                 }
             });
             if (!signUpResponse || "error" in signUpResponse) {
-                return sse(c, async (stream)=>{
-                    await stream.toast("Failed to create account", "error");
-                });
+                return dsToast("Failed to create account", "error");
             }
             await c.var.services.settings.completeOnboarding();
-            return sse(c, async (stream)=>{
-                await stream.redirect("/signin?setup");
-            });
+            return dsRedirect("/signin?setup");
         } catch (err) {
             // eslint-disable-next-line no-console -- Error logging is intentional
             console.error("Setup error:", err);
-            return sse(c, async (stream)=>{
-                await stream.toast("Failed to create account", "error");
-            });
+            return dsToast("Failed to create account", "error");
         }
     });
     // Signin page component
@@ -398,9 +386,7 @@ import { getAvailableThemes, buildThemeStyle } from "./lib/theme.js";
     });
     app.post("/signin", async (c)=>{
         if (!c.var.auth) {
-            return sse(c, async (stream)=>{
-                await stream.toast("Auth not configured", "error");
-            });
+            return dsToast("Auth not configured", "error");
         }
         const body = await c.req.json();
         const { email, password } = body;
@@ -417,9 +403,7 @@ import { getAvailableThemes, buildThemeStyle } from "./lib/theme.js";
             });
             const response = await c.var.auth.handler(signInRequest);
             if (!response.ok) {
-                return sse(c, async (stream)=>{
-                    await stream.toast("Invalid email or password", "error");
-                });
+                return dsToast("Invalid email or password", "error");
             }
             // Forward Set-Cookie headers from auth response
             const cookieHeaders = {};
@@ -427,17 +411,13 @@ import { getAvailableThemes, buildThemeStyle } from "./lib/theme.js";
             if (setCookie) {
                 cookieHeaders["Set-Cookie"] = setCookie;
             }
-            return sse(c, async (stream)=>{
-                await stream.redirect("/dash");
-            }, {
+            return dsRedirect("/dash", {
                 headers: cookieHeaders
             });
         } catch (err) {
             // eslint-disable-next-line no-console -- Error logging is intentional
             console.error("Signin error:", err);
-            return sse(c, async (stream)=>{
-                await stream.toast("Invalid email or password", "error");
-            });
+            return dsToast("Invalid email or password", "error");
         }
     });
     app.get("/signout", async (c)=>{
@@ -612,29 +592,21 @@ import { getAvailableThemes, buildThemeStyle } from "./lib/theme.js";
         // Validate token
         const stored = await c.var.services.settings.get(SETTINGS_KEYS.PASSWORD_RESET_TOKEN);
         if (!stored) {
-            return sse(c, async (stream)=>{
-                await stream.toast("Invalid or expired reset link.", "error");
-            });
+            return dsToast("Invalid or expired reset link.", "error");
         }
         const separatorIndex = stored.lastIndexOf(":");
         const storedToken = stored.substring(0, separatorIndex);
         const expiry = parseInt(stored.substring(separatorIndex + 1), 10);
         const now = Math.floor(Date.now() / 1000);
         if (token !== storedToken || now > expiry) {
-            return sse(c, async (stream)=>{
-                await stream.toast("Invalid or expired reset link.", "error");
-            });
+            return dsToast("Invalid or expired reset link.", "error");
         }
         // Validate passwords
         if (!password || password.length < 8) {
-            return sse(c, async (stream)=>{
-                await stream.toast("Password must be at least 8 characters.", "error");
-            });
+            return dsToast("Password must be at least 8 characters.", "error");
         }
         if (password !== confirmPassword) {
-            return sse(c, async (stream)=>{
-                await stream.toast("Passwords do not match.", "error");
-            });
+            return dsToast("Passwords do not match.", "error");
         }
         try {
             const hashedPassword = await hashPassword(password);
@@ -642,9 +614,7 @@ import { getAvailableThemes, buildThemeStyle } from "./lib/theme.js";
             // Get admin user
             const userResult = await db.prepare("SELECT id FROM user LIMIT 1").first();
             if (!userResult) {
-                return sse(c, async (stream)=>{
-                    await stream.toast("No user account found.", "error");
-                });
+                return dsToast("No user account found.", "error");
             }
             // Update password
             await db.prepare("UPDATE account SET password = ? WHERE user_id = ? AND provider_id = 'credential'").bind(hashedPassword, userResult.id).run();
@@ -652,15 +622,11 @@ import { getAvailableThemes, buildThemeStyle } from "./lib/theme.js";
             await db.prepare("DELETE FROM session WHERE user_id = ?").bind(userResult.id).run();
             // Delete the reset token
             await c.var.services.settings.remove(SETTINGS_KEYS.PASSWORD_RESET_TOKEN);
-            return sse(c, async (stream)=>{
-                await stream.redirect("/signin?reset");
-            });
+            return dsRedirect("/signin?reset");
         } catch (err) {
             // eslint-disable-next-line no-console -- Error logging is intentional
             console.error("Password reset error:", err);
-            return sse(c, async (stream)=>{
-                await stream.toast("Failed to reset password.", "error");
-            });
+            return dsToast("Failed to reset password.", "error");
         }
     });
     // Dashboard routes (protected)

package/dist/client.js

@@ -8,3 +8,4 @@
  */ import "./vendor/datastar.js";
 import "basecoat-css/all";
 import "./lib/image-processor.js";
+import "./lib/media-upload.js";

package/dist/lib/image-processor.js

@@ -185,7 +185,3 @@ export const ImageProcessor = {
     process,
     processToFile
 };
-// Expose globally for inline scripts
-if (typeof window !== "undefined") {
-    window.ImageProcessor = ImageProcessor;
-}

package/dist/lib/media-upload.js

@@ -0,0 +1,104 @@
+/**
+ * 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) {
+    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() {
+    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, fileSize, statusText) {
+    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, fileName, errorMessage) {
+    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, file) {
+    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");
+        const form = document.getElementById("upload-form");
+        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() {
+    document.addEventListener("change", (e)=>{
+        const input = e.target.closest("[data-media-upload]");
+        if (!input?.files?.[0]) return;
+        handleUpload(input, input.files[0]);
+    });
+}
+initMediaUpload();

package/dist/lib/sse.d.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";
 /**
@@ -135,4 +136,57 @@ export interface SSEStream {
 export declare function sse(c: Context, handler: (stream: SSEStream) => Promise<void>, options?: {
     headers?: Record<string, string>;
 }): Response;
+/**
+ * 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 declare function dsRedirect(url: string, options?: {
+    headers?: Record<string, string>;
+}): Response;
+/**
+ * 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 declare function dsToast(message: string, type?: "success" | "error"): Response;
+/**
+ * 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 declare function dsSignals(signals: Record<string, unknown>): Response;
 //# sourceMappingURL=sse.d.ts.map

package/dist/lib/sse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/lib/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB,OAAO,GACP,OAAO,GACP,SAAS,GACT,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;OAUG;IACH,YAAY,CACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GACpC,IAAI,CAAC;IAER;;;;;;;;;;;;;;;;;OAiBG;IACH,aAAa,CACX,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,SAAS,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC7B,GACA,IAAI,CAAC;IAER;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,IAAI,CAAC;CAC1D;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,GAAG,CACjB,CAAC,EAAE,OAAO,EACV,OAAO,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,EAC7C,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC7C,QAAQ,CAiGV"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/lib/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB,OAAO,GACP,OAAO,GACP,SAAS,GACT,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;OAUG;IACH,YAAY,CACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GACpC,IAAI,CAAC;IAER;;;;;;;;;;;;;;;;;OAiBG;IACH,aAAa,CACX,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,SAAS,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC7B,GACA,IAAI,CAAC;IAER;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,IAAI,CAAC;CAC1D;AA+CD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,GAAG,CACjB,CAAC,EAAE,OAAO,EACV,OAAO,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,EAC7C,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC7C,QAAQ,CAoFV;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC7C,QAAQ,CASV;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,SAAS,GAAG,OAAmB,GACpC,QAAQ,CAQV;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,CAIpE"}

package/dist/lib/sse.js

@@ -1,21 +1,39 @@
 /**
- * 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/
+ */ // ---------------------------------------------------------------------------
+// Shared internal helpers (used by both SSE and non-SSE response builders)
+// ---------------------------------------------------------------------------
+/** Build the redirect script tag for Datastar patch-elements */ function buildRedirectScript(url) {
+    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, type) {
+    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
  *
  * @param eventType - The Datastar event type (e.g. "datastar-patch-elements")
@@ -88,10 +106,8 @@
                     controller.enqueue(encoder.encode(formatEvent("datastar-patch-elements", dataLines)));
                 },
                 redirect (url) {
-                    const escapedUrl = url.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-                    const script = `<script data-effect="el.remove()">window.location.href='${escapedUrl}'</script>`;
                     const dataLines = [
-                        `elements ${script}`,
+                        `elements ${buildRedirectScript(url)}`,
                         "mode append",
                         "selector body"
                     ];
@@ -105,13 +121,8 @@
                     ])));
                 },
                 toast (message, type = "success") {
-                    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;");
-                    const html = `<div class="toast ${cls}" data-init="setTimeout(() => { el.classList.add('toast-out'); el.addEventListener('animationend', () => el.remove()) }, 3000)">${icon}<span>${escapedMessage}</span>${closeBtn}</div>`;
                     const dataLines = [
-                        `elements ${html}`,
+                        `elements ${buildToastHtml(message, type)}`,
                         "mode append",
                         "selector #toast-container"
                     ];
@@ -132,3 +143,77 @@
         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, options) {
+    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, type = "success") {
+    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) {
+    return new Response(JSON.stringify(signals), {
+        headers: {
+            "Content-Type": "application/json"
+        }
+    });
+}

package/dist/routes/api/upload.js

@@ -7,7 +7,7 @@
 import { html } from "hono/html";
 import { requireAuthApi } from "../../middleware/auth.js";
 import { getMediaUrl, getImageUrl } from "../../lib/image.js";
-import { sse } from "../../lib/sse.js";
+import { sse, dsSignals } from "../../lib/sse.js";
 export const uploadApiRoutes = new Hono();
 // Require auth for all upload routes
 uploadApiRoutes.use("*", requireAuthApi());
@@ -88,10 +88,8 @@ function formatSize(bytes) {
 uploadApiRoutes.post("/", async (c)=>{
     if (!c.env.R2) {
         if (wantsSSE(c)) {
-            return sse(c, async (stream)=>{
-                await stream.patchSignals({
-                    _uploadError: "R2 storage not configured"
-                });
+            return dsSignals({
+                _uploadError: "R2 storage not configured"
             });
         }
         return c.json({
@@ -102,10 +100,8 @@ uploadApiRoutes.post("/", async (c)=>{
     const file = formData.get("file");
     if (!file) {
         if (wantsSSE(c)) {
-            return sse(c, async (stream)=>{
-                await stream.patchSignals({
-                    _uploadError: "No file provided"
-                });
+            return dsSignals({
+                _uploadError: "No file provided"
             });
         }
         return c.json({
@@ -122,10 +118,8 @@ uploadApiRoutes.post("/", async (c)=>{
     ];
     if (!allowedTypes.includes(file.type)) {
         if (wantsSSE(c)) {
-            return sse(c, async (stream)=>{
-                await stream.patchSignals({
-                    _uploadError: "File type not allowed"
-                });
+            return dsSignals({
+                _uploadError: "File type not allowed"
             });
         }
         return c.json({
@@ -136,10 +130,8 @@ uploadApiRoutes.post("/", async (c)=>{
     const maxSize = 10 * 1024 * 1024;
     if (file.size > maxSize) {
         if (wantsSSE(c)) {
-            return sse(c, async (stream)=>{
-                await stream.patchSignals({
-                    _uploadError: "File too large (max 10MB)"
-                });
+            return dsSignals({
+                _uploadError: "File too large (max 10MB)"
             });
         }
         return c.json({
@@ -176,6 +168,7 @@ uploadApiRoutes.post("/", async (c)=>{
                     mode: "outer",
                     selector: "#upload-placeholder"
                 });
+                await stream.toast("Upload successful!");
             });
         }
         // JSON response for API clients
@@ -190,7 +183,12 @@ uploadApiRoutes.post("/", async (c)=>{
     } catch (err) {
         // eslint-disable-next-line no-console -- Error logging is intentional
         console.error("Upload error:", err);
-        // Return error - client will handle updating the placeholder
+        if (wantsSSE(c)) {
+            return sse(c, async (stream)=>{
+                await stream.remove("#upload-placeholder");
+                await stream.toast("Upload failed. Please try again.", "error");
+            });
+        }
         return c.json({
             error: "Upload failed"
         }, 500);