bosia 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bosia",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "description": "A fast, batteries-included fullstack framework — SSR · Svelte 5 Runes · Bun · ElysiaJS. File-based routing inspired by SvelteKit. No Node.js, no Vite, no adapters.",
   "keywords": [
@@ -31,7 +31,8 @@
     "package.json"
   ],
   "exports": {
-    ".": "./src/lib/index.ts"
+    ".": "./src/lib/index.ts",
+    "./client": "./src/lib/client.ts"
   },
   "bin": {
     "bosia": "src/cli/index.ts"

package/src/cli/feat.ts

@@ -1,4 +1,4 @@
-import { join, dirname } from "path";
+import { join, dirname, extname } from "path";
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from "fs";
 import * as p from "@clack/prompts";
 import { addComponent, initAddRegistry } from "./add.ts";
@@ -16,13 +16,26 @@ import {
 // registry with --local) and copies route/lib files, installs npm deps.
 // Supports nested feature dependencies (e.g. todo → drizzle).
 
+type FileStrategy =
+    | "write"            // overwrite (prompt if interactive)
+    | "skip-if-exists"   // bootstrap-once: never replace user copy
+    | "append-line"      // idempotent line append (barrel re-exports)
+    | "append-block"     // marker-delimited block, replaced by id on re-install
+    | "merge-json";      // deep-merge JSON, preserve existing keys
+
+interface FileEntry {
+    src: string;
+    target: string;
+    strategy?: FileStrategy;
+    marker?: string;     // unique id within target (default = feature name)
+}
+
 interface FeatureMeta {
     name: string;
     description: string;
     features?: string[];               // other bosia features required
     components: string[];              // bosia components to install via `bosia add`
-    files: string[];                   // source filenames in the registry feature dir
-    targets: string[];                 // destination paths relative to project root
+    files: FileEntry[];                // file entries with per-file strategy
     npmDeps: Record<string, string>;
     npmDevDeps?: Record<string, string>;
     scripts?: Record<string, string>;  // package.json scripts to add
@@ -82,32 +95,26 @@ export async function installFeature(name: string, isRoot: boolean, options?: In
         console.log("");
     }
 
-    // Copy feature files to their target paths
+    // Apply each file entry per its strategy
     const createdDirs = new Set<string>();
-    for (let i = 0; i < meta.files.length; i++) {
-        const file = meta.files[i]!;
-        const target = meta.targets[i] ?? file;
-        const dest = join(cwd, target);
-
-        // Prompt before overwriting existing files (skip check entirely in non-interactive mode)
-        if (!options?.skipPrompts && existsSync(dest)) {
-            const replace = await p.confirm({
-                message: `File "${target}" already exists. Replace it?`,
-            });
-            if (p.isCancel(replace) || !replace) {
-                console.log(`   ⏭️  Skipped ${target}`);
-                continue;
-            }
-        }
-
-        const content = await readRegistryFile(registryRoot, "features", name, file);
+    for (const entry of meta.files) {
+        const dest = join(cwd, entry.target);
+        const strategy: FileStrategy = entry.strategy ?? "write";
         const dir = dirname(dest);
         if (!createdDirs.has(dir)) {
             mkdirSync(dir, { recursive: true });
             createdDirs.add(dir);
         }
-        writeFileSync(dest, content, "utf-8");
-        console.log(`   ✍️  ${target}`);
+        const content = await readRegistryFile(registryRoot, "features", name, entry.src);
+        await applyStrategy({
+            dest,
+            target: entry.target,
+            content,
+            strategy,
+            feat: name,
+            marker: entry.marker ?? name,
+            skipPrompts: options?.skipPrompts ?? false,
+        });
     }
 
     // Install npm dependencies
@@ -162,5 +169,149 @@ export async function installFeature(name: string, isRoot: boolean, options?: In
     }
 }
 
+// ─── File strategies ──────────────────────────────────────
+
+interface StrategyArgs {
+    dest: string;
+    target: string;
+    content: string;
+    strategy: FileStrategy;
+    feat: string;
+    marker: string;
+    skipPrompts: boolean;
+}
+
+async function applyStrategy(args: StrategyArgs): Promise<void> {
+    const { dest, target, content, strategy, feat, marker, skipPrompts } = args;
+
+    switch (strategy) {
+        case "write": {
+            if (existsSync(dest) && !skipPrompts) {
+                const replace = await p.confirm({
+                    message: `File "${target}" already exists. Replace it?`,
+                });
+                if (p.isCancel(replace) || !replace) {
+                    console.log(`   ⏭️  Skipped ${target}`);
+                    return;
+                }
+            }
+            writeFileSync(dest, content, "utf-8");
+            console.log(`   ✍️  ${target}`);
+            return;
+        }
+
+        case "skip-if-exists": {
+            if (existsSync(dest)) {
+                console.log(`   ⏭️  Kept existing ${target}`);
+                return;
+            }
+            writeFileSync(dest, content, "utf-8");
+            console.log(`   ✍️  ${target}`);
+            return;
+        }
+
+        case "append-line": {
+            const existing = existsSync(dest) ? readFileSync(dest, "utf-8") : "";
+            const existingLines = new Set(
+                existing.split("\n").map((l) => l.trim()).filter(Boolean),
+            );
+            const newLines = content
+                .split("\n")
+                .map((l) => l.trim())
+                .filter(Boolean)
+                .filter((l) => !existingLines.has(l));
+
+            if (newLines.length === 0) {
+                console.log(`   ⏭️  ${target} (no new lines)`);
+                return;
+            }
+
+            const nl = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+            writeFileSync(dest, existing + nl + newLines.join("\n") + "\n", "utf-8");
+            console.log(`   ➕ ${target} (+${newLines.length} line${newLines.length === 1 ? "" : "s"})`);
+            return;
+        }
+
+        case "append-block": {
+            const id = `bosia:${feat}:${marker}`;
+            const delim = blockDelim(extname(dest));
+            const startLine = delim.end
+                ? `${delim.start} >>> ${id} ${delim.end}`
+                : `${delim.start} >>> ${id}`;
+            const endLine = delim.end
+                ? `${delim.start} <<< ${id} ${delim.end}`
+                : `${delim.start} <<< ${id}`;
+            const block = `${startLine}\n${content.trimEnd()}\n${endLine}`;
+
+            const existing = existsSync(dest) ? readFileSync(dest, "utf-8") : "";
+
+            if (existing.includes(startLine) && existing.includes(endLine)) {
+                const re = new RegExp(
+                    `${escapeRegex(startLine)}[\\s\\S]*?${escapeRegex(endLine)}`,
+                );
+                writeFileSync(dest, existing.replace(re, block), "utf-8");
+                console.log(`   ♻️  ${target} (replaced ${id})`);
+            } else {
+                const nl = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+                writeFileSync(dest, existing + nl + block + "\n", "utf-8");
+                console.log(`   ➕ ${target} (appended ${id})`);
+            }
+            return;
+        }
+
+        case "merge-json": {
+            const existing = existsSync(dest)
+                ? JSON.parse(readFileSync(dest, "utf-8"))
+                : {};
+            const incoming = JSON.parse(content);
+            const merged = mergeJsonPreserve(existing, incoming);
+            writeFileSync(dest, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+            console.log(`   🔀 ${target} (merged json)`);
+            return;
+        }
+
+        default: {
+            const _exhaustive: never = strategy;
+            throw new Error(`Unknown file strategy: ${_exhaustive}`);
+        }
+    }
+}
+
+function blockDelim(ext: string): { start: string; end: string } {
+    if (ext === ".html" || ext === ".svelte") return { start: "<!--", end: "-->" };
+    if (ext === ".css") return { start: "/*", end: "*/" };
+    return { start: "//", end: "" };
+}
+
+function escapeRegex(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// Deep-merge `source` into `target`, preserving existing target values.
+// Objects: recurse. Arrays: concat-dedupe by JSON identity. Primitives: keep target.
+function mergeJsonPreserve(target: unknown, source: unknown): unknown {
+    if (Array.isArray(target) && Array.isArray(source)) {
+        const out = [...target];
+        for (const item of source) {
+            if (!out.some((x) => JSON.stringify(x) === JSON.stringify(item))) {
+                out.push(item);
+            }
+        }
+        return out;
+    }
+    if (isPlainObject(target) && isPlainObject(source)) {
+        const out: Record<string, unknown> = { ...target };
+        for (const [k, v] of Object.entries(source)) {
+            out[k] = k in target ? mergeJsonPreserve(target[k], v) : v;
+        }
+        return out;
+    }
+    return target !== undefined ? target : source;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
 // Re-exports for create.ts
 export { resolveLocalRegistry, type InstallOptions } from "./registry.ts";

package/src/core/client/App.svelte

@@ -3,6 +3,7 @@
   import { findMatch } from "../matcher.ts";
   import { clientRoutes } from "bosia:routes";
   import { consumePrefetch, prefetchCache, dataUrl } from "./prefetch.ts";
+  import { appState } from "./appState.svelte.ts";
 
   let {
     ssrMode = false,
@@ -22,11 +23,13 @@
 
   let PageComponent = $state<any>(ssrPageComponent);
   let layoutComponents = $state<any[]>(ssrLayoutComponents ?? []);
-  let pageData = $state<Record<string, any>>(ssrPageData ?? {});
-  let layoutData = $state<Record<string, any>[]>(ssrLayoutData ?? []);
-  // Kept separate to avoid a read→write cycle inside the $effect below
-  let routeParams = $state<Record<string, string>>(ssrPageData?.params ?? {});
-  let formData = $state<any>(ssrFormData);
+  // In SSR mode, render directly from props (server module singletons must
+  // not hold per-request state). On the client, read/write through `appState`
+  // so `use:enhance` and other helpers can update the same cells.
+  const pageData = $derived(ssrMode ? (ssrPageData ?? {}) : appState.pageData);
+  const layoutData = $derived(ssrMode ? (ssrLayoutData ?? []) : appState.layoutData);
+  const routeParams = $derived(ssrMode ? (ssrPageData?.params ?? {}) : appState.routeParams);
+  const formData = $derived(ssrMode ? ssrFormData : appState.form);
   let navigating = $state(false);
   let navDone = $state(false);
   // Skip bar on the very first effect run (initial hydration — data already present)
@@ -47,7 +50,7 @@
     firstNav = false;
     if (isFirst) return; // Initial hydration — data already in SSR props, no fetch needed
 
-    formData = null;
+    appState.form = null;
     if (navDoneTimer) { clearTimeout(navDoneTimer); navDoneTimer = null; }
     navDone = false;
     navigating = true;
@@ -82,9 +85,9 @@
       }
       PageComponent = pageMod.default;
       layoutComponents = layoutMods.map((m: any) => m.default);
-      pageData = result?.pageData ?? {};
-      layoutData = result?.layoutData ?? [];
-      routeParams = result?.pageData?.params ?? match.params;
+      appState.pageData = result?.pageData ?? {};
+      appState.layoutData = result?.layoutData ?? [];
+      appState.routeParams = result?.pageData?.params ?? match.params;
 
       // Scroll to top on forward navigation (not on popstate/back-forward)
       if (router.isPush) window.scrollTo(0, 0);

package/src/core/client/appState.svelte.ts

@@ -0,0 +1,55 @@
+// ─── Shared App State ─────────────────────────────────────
+// Singleton holding reactive cells that App.svelte renders from.
+// Lives in a module so client-side helpers (e.g. `use:enhance`)
+// can read and update the same state without going through props.
+//
+// Server-side: never touched. App.svelte's template branches on
+// `ssrMode` and reads from `ssrXxx` props directly during SSR,
+// so concurrent requests don't share these cells.
+
+import { dataUrl } from "./prefetch.ts";
+import { router } from "./router.svelte.ts";
+
+class AppState {
+    pageData = $state<Record<string, any>>({});
+    layoutData = $state<Record<string, any>[]>([]);
+    routeParams = $state<Record<string, string>>({});
+    form = $state<any>(null);
+}
+
+export const appState = new AppState();
+
+/**
+ * Re-fetch loader data for the given path and apply to `appState`.
+ * Used by `use:enhance` after a successful action — mirrors SvelteKit's
+ * `invalidateAll` default. No-op if the fetch fails or returns an error.
+ */
+export async function refreshData(path: string): Promise<void> {
+    try {
+        const res = await fetch(dataUrl(path));
+        if (!res.ok) return;
+        const result = await res.json();
+        if (result?.redirect) {
+            router.navigate(result.redirect);
+            return;
+        }
+        if (result?.error) return;
+        appState.pageData = result?.pageData ?? {};
+        appState.layoutData = result?.layoutData ?? [];
+        appState.routeParams = result?.pageData?.params ?? appState.routeParams;
+        if (result?.metadata) {
+            if (result.metadata.title) document.title = result.metadata.title;
+            if (result.metadata.description) {
+                let meta = document.querySelector('meta[name="description"]') as HTMLMetaElement | null;
+                if (!meta) {
+                    meta = document.createElement("meta");
+                    meta.name = "description";
+                    document.head.appendChild(meta);
+                }
+                meta.content = result.metadata.description;
+            }
+        }
+    } catch {
+        // best-effort — silently swallow
+    }
+}

package/src/core/client/enhance.ts

@@ -0,0 +1,107 @@
+// ─── use:enhance ──────────────────────────────────────────
+// Progressive enhancement for `<form method="POST">`. Intercepts
+// submission, POSTs via fetch with `x-bosia-action: 1`, parses the
+// JSON action result, and updates shared form/page state without a
+// full page reload. Falls back to native form submission when JS is
+// disabled because nothing is wired up until this action runs.
+
+import { appState, refreshData } from "./appState.svelte.ts";
+import { router } from "./router.svelte.ts";
+
+export type ActionResult =
+    | { type: "success"; status: number; data: any }
+    | { type: "failure"; status: number; data: any }
+    | { type: "redirect"; status: number; location: string }
+    | { type: "error"; status: number; message: string };
+
+export type SubmitFunction = (input: {
+    formData: FormData;
+    formElement: HTMLFormElement;
+    action: URL;
+    cancel: () => void;
+    submitter: HTMLElement | null;
+}) => void | ((opts: {
+    result: ActionResult;
+    formElement: HTMLFormElement;
+    update: (opts?: { reset?: boolean; invalidateAll?: boolean }) => Promise<void>;
+}) => void | Promise<void>);
+
+async function applyResult(
+    result: ActionResult,
+    form: HTMLFormElement,
+    opts: { reset?: boolean; invalidateAll?: boolean } = {},
+): Promise<void> {
+    const reset = opts.reset !== false;
+    const invalidateAll = opts.invalidateAll !== false;
+
+    if (result.type === "redirect") {
+        router.navigate(result.location);
+        return;
+    }
+    if (result.type === "error") {
+        appState.form = { error: { message: result.message, status: result.status } };
+        console.warn(`[bosia] action error ${result.status}: ${result.message}`);
+        return;
+    }
+    if (result.type === "failure") {
+        appState.form = result.data;
+        return;
+    }
+    // success
+    appState.form = result.data;
+    if (reset) form.reset();
+    if (invalidateAll) {
+        await refreshData(window.location.pathname + window.location.search);
+    }
+}
+
+export function enhance(form: HTMLFormElement, submit?: SubmitFunction) {
+    async function handleSubmit(event: SubmitEvent) {
+        event.preventDefault();
+
+        const submitter = (event.submitter as HTMLElement | null) ?? null;
+        const formData = new FormData(form, submitter as HTMLElement | undefined);
+
+        // Resolve action URL — preserve `?/actionName` if the submitter or form sets it
+        const actionAttr = (submitter as HTMLButtonElement | HTMLInputElement | null)?.formAction
+            || form.action
+            || window.location.href;
+        const action = new URL(actionAttr, window.location.href);
+
+        let cancelled = false;
+        const cancel = () => { cancelled = true; };
+
+        const callback = submit?.({ formData, formElement: form, action, cancel, submitter });
+        if (cancelled) return;
+
+        let result: ActionResult;
+        try {
+            const res = await fetch(action, {
+                method: "POST",
+                body: formData,
+                headers: { "x-bosia-action": "1", accept: "application/json" },
+            });
+            result = await res.json() as ActionResult;
+        } catch (err) {
+            const message = (err as Error)?.message ?? "Network error";
+            result = { type: "error", status: 0, message };
+            console.warn("[bosia] enhance: submission failed", err);
+        }
+
+        const update = (opts?: { reset?: boolean; invalidateAll?: boolean }) =>
+            applyResult(result, form, opts ?? {});
+
+        if (typeof callback === "function") {
+            await callback({ result, formElement: form, update });
+        } else {
+            await update();
+        }
+    }
+
+    form.addEventListener("submit", handleSubmit);
+    return {
+        destroy() {
+            form.removeEventListener("submit", handleSubmit);
+        },
+    };
+}

package/src/core/client/hydrate.ts

@@ -1,9 +1,10 @@
-import { hydrate } from "svelte";
+import { hydrate, mount } from "svelte";
 import App from "./App.svelte";
 import { router } from "./router.svelte.ts";
 import { initPrefetch } from "./prefetch.ts";
 import { findMatch, compileRoutes } from "../matcher.ts";
 import { clientRoutes } from "bosia:routes";
+import { appState } from "./appState.svelte.ts";
 
 // Pre-compile route patterns into RegExp at startup (shared by App.svelte and router via module reference)
 compileRoutes(clientRoutes);
@@ -34,17 +35,34 @@ async function main() {
         router.params = match.params;
     }
 
-    hydrate(App, {
-        target: document.getElementById("app")!,
-        props: {
-            ssrMode: false,
-            ssrPageComponent,
-            ssrLayoutComponents,
-            ssrPageData: (window as any).__BOSIA_PAGE_DATA__ ?? {},
-            ssrLayoutData: (window as any).__BOSIA_LAYOUT_DATA__ ?? [],
-            ssrFormData: (window as any).__BOSIA_FORM_DATA__ ?? null,
-        },
-    });
+    const ssrPageData = (window as any).__BOSIA_PAGE_DATA__ ?? {};
+    const ssrLayoutData = (window as any).__BOSIA_LAYOUT_DATA__ ?? [];
+    const ssrFormData = (window as any).__BOSIA_FORM_DATA__ ?? null;
+
+    // Seed shared client state so `use:enhance` and other helpers
+    // start from the same values App.svelte renders during hydration.
+    appState.pageData = ssrPageData;
+    appState.layoutData = ssrLayoutData;
+    appState.routeParams = ssrPageData?.params ?? (match?.params ?? {});
+    appState.form = ssrFormData;
+
+    const target = document.getElementById("app")!;
+    const props = {
+        ssrMode: false,
+        ssrPageComponent,
+        ssrLayoutComponents,
+        ssrPageData,
+        ssrLayoutData,
+        ssrFormData,
+    };
+
+    // ssr=false → server shipped empty shell, no hydration markers exist.
+    // Use mount() instead of hydrate() to render fresh on the client.
+    if ((window as any).__BOSIA_SSR__ === false) {
+        mount(App, { target, props });
+    } else {
+        hydrate(App, { target, props });
+    }
 }
 
 main();

package/src/core/env.ts

@@ -61,6 +61,26 @@ function parseEnvFile(content: string, filename?: string): Record<string, string
         }
 
         let value = trimmed.slice(eqIdx + 1).trim();
+        // Strip inline comments before quote-unescaping.
+        // Quoted: find the real closing quote, verify trailing chars are whitespace+comment, truncate.
+        // Unquoted: strip \s+#... (no space before # keeps foo#bar intact).
+        if (value.startsWith('"')) {
+            let end = -1;
+            for (let j = 1; j < value.length; j++) {
+                if (value[j] === "\\") { j++; continue; } // skip escaped char
+                if (value[j] === '"') { end = j; break; }
+            }
+            if (end !== -1 && /^\s*(#.*)?$/.test(value.slice(end + 1))) {
+                value = value.slice(0, end + 1);
+            }
+        } else if (value.startsWith("'")) {
+            const end = value.indexOf("'", 1);
+            if (end !== -1 && /^\s*(#.*)?$/.test(value.slice(end + 1))) {
+                value = value.slice(0, end + 1);
+            }
+        } else {
+            value = value.startsWith("#") ? "" : value.replace(/\s+#.*$/, "");
+        }
         // Double-quoted: process escape sequences
         if (value.startsWith('"') && value.endsWith('"')) {
             value = processEscapes(value.slice(1, -1));

package/src/core/html.ts

@@ -55,6 +55,13 @@ function getPublicDynamicEnv(): Record<string, string> {
     return result;
 }
 
+// ─── Lang Validation ──────────────────────────────────────
+
+const LANG_RE = /^[a-zA-Z0-9-]{1,35}$/;
+function safeLang(lang?: string): string {
+    return lang && LANG_RE.test(lang) ? lang : "en";
+}
+
 // ─── HTML Builder ─────────────────────────────────────────
 
 export function buildHtml(
@@ -65,6 +72,7 @@ export function buildHtml(
     csr = true,
     formData: any = null,
     lang?: string,
+    ssr = true,
 ): string {
     const cssLinks = (distManifest.css ?? [])
         .map((f: string) => `<link rel="stylesheet" href="/dist/client/${f}">`)
@@ -80,15 +88,16 @@ export function buildHtml(
     const formScript = formData != null
         ? `window.__BOSIA_FORM_DATA__=${safeJsonStringify(formData)};`
         : "";
+    const ssrFlag = ssr ? "" : "window.__BOSIA_SSR__=false;";
 
     const scripts = csr
-        ? `${envScript}\n  <script>window.__BOSIA_PAGE_DATA__=${safeJsonStringify(pageData)};window.__BOSIA_LAYOUT_DATA__=${safeJsonStringify(layoutData)};${formScript}</script>\n  <script type="module" src="/dist/client/${distManifest.entry}${cacheBust}"></script>`
+        ? `${envScript}\n  <script>${ssrFlag}window.__BOSIA_PAGE_DATA__=${safeJsonStringify(pageData)};window.__BOSIA_LAYOUT_DATA__=${safeJsonStringify(layoutData)};${formScript}</script>\n  <script type="module" src="/dist/client/${distManifest.entry}${cacheBust}"></script>`
         : isDev
             ? `\n  <script>!function r(){var e=new EventSource("/__bosia/sse");e.addEventListener("reload",()=>location.reload());e.onopen=()=>r._ok||(r._ok=1);e.onerror=()=>{e.close();setTimeout(r,2000)}}()</script>`
             : "";
 
     return `<!DOCTYPE html>
-<html lang="${lang || "en"}">
+<html lang="${safeLang(lang)}">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
@@ -113,7 +122,7 @@ const _shellOpenCache = new Map<string, string>();
 
 /** Chunk 1: everything from <!DOCTYPE> through CSS/modulepreload links (head still open) */
 export function buildHtmlShellOpen(lang?: string): string {
-    const key = lang || "en";
+    const key = safeLang(lang);
     const cached = _shellOpenCache.get(key);
     if (cached) return cached;
     const cssLinks = (distManifest.css ?? [])
@@ -181,6 +190,7 @@ export function buildHtmlTail(
     layoutData: any[],
     csr: boolean,
     formData: any = null,
+    ssr = true,
 ): string {
     let out = `<script>document.getElementById('__bs__').remove()</script>`;
     out += `\n<div id="app">${body}</div>`;
@@ -191,7 +201,8 @@ export function buildHtmlTail(
             out += `\n<script>window.__BOSIA_ENV__=${safeJsonStringify(publicEnv)};</script>`;
         }
         const formInject = formData != null ? `window.__BOSIA_FORM_DATA__=${safeJsonStringify(formData)};` : "";
-        out += `\n<script>window.__BOSIA_PAGE_DATA__=${safeJsonStringify(pageData)};` +
+        const ssrFlag = ssr ? "" : "window.__BOSIA_SSR__=false;";
+        out += `\n<script>${ssrFlag}window.__BOSIA_PAGE_DATA__=${safeJsonStringify(pageData)};` +
                `window.__BOSIA_LAYOUT_DATA__=${safeJsonStringify(layoutData)};${formInject}</script>`;
         out += `\n<script type="module" src="/dist/client/${distManifest.entry}${cacheBust}"></script>`;
     } else if (isDev) {
@@ -203,15 +214,18 @@ export function buildHtmlTail(
 
 // ─── Gzip Compression ────────────────────────────────────
 
+const GZIP_MIN_BYTES = 2048;
+
 export function compress(body: string, contentType: string, req: Request, status = 200, extraHeaders?: Record<string, string>): Response {
     const headers: Record<string, string> = { "Content-Type": contentType, "Vary": "Accept-Encoding", ...extraHeaders };
     const accept = req.headers.get("accept-encoding") ?? "";
+    const bytes = new TextEncoder().encode(body);
     // Skip compression in dev — the dev proxy's fetch() auto-decompresses gzip
     // responses but keeps the Content-Encoding header, causing ERR_CONTENT_DECODING_FAILED.
-    if (!isDev && body.length > 1024 && accept.includes("gzip")) {
-        return new Response(Bun.gzipSync(body), { status, headers: { ...headers, "Content-Encoding": "gzip" } });
+    if (!isDev && bytes.length > GZIP_MIN_BYTES && accept.includes("gzip")) {
+        return new Response(Bun.gzipSync(bytes), { status, headers: { ...headers, "Content-Encoding": "gzip" } });
     }
-    return new Response(body, { status, headers });
+    return new Response(bytes, { status, headers });
 }
 
 // ─── Static File Detection ────────────────────────────────

package/src/core/prerender.ts

@@ -17,6 +17,10 @@ async function detectPrerenderRoutes(manifest: RouteManifest): Promise<string[]>
         const filePath = join("src", "routes", route.pageServer);
         const content = await Bun.file(filePath).text();
         if (!/export\s+const\s+prerender\s*=\s*true/.test(content)) continue;
+        if (/export\s+const\s+ssr\s*=\s*false/.test(content)) {
+            console.warn(`   ⚠️  ${route.pattern} has prerender=true && ssr=false — contradictory, skipped`);
+            continue;
+        }
 
         if (route.pattern.includes("[")) {
             // Dynamic route — import module and call entries() to get param values

package/src/core/renderer.ts

@@ -136,10 +136,12 @@ export async function loadRouteData(
     // Run page server loader
     let pageData: Record<string, any> = {};
     let csr = true;
+    let ssr = true;
     if (route.pageServer) {
         try {
             const mod = await route.pageServer();
             if (mod.csr === false) csr = false;
+            if (mod.ssr === false) ssr = false;
             if (typeof mod.load === "function") {
                 const parent = async () => {
                     const merged: Record<string, any> = {};
@@ -156,7 +158,7 @@ export async function loadRouteData(
         }
     }
 
-    return { pageData: { ...pageData, params }, layoutData, csr };
+    return { pageData: { ...pageData, params }, layoutData, csr, ssr };
 }
 
 // ─── Metadata Loader ─────────────────────────────────────
@@ -247,6 +249,17 @@ export async function renderSSRStream(
             controller.enqueue(enc.encode(buildMetadataChunk(metadata)));
 
             try {
+                if (!data!.ssr) {
+                    // ssr=false → skip render(); ship empty shell + hydration scripts.
+                    // ssr=false && csr=false is meaningless (nothing renders) — force csr=true.
+                    if (!data!.csr && isDev) {
+                        console.warn(`⚠️  ${url.pathname}: ssr=false && csr=false renders nothing — forcing csr=true`);
+                    }
+                    controller.enqueue(enc.encode(buildHtmlTail("", "", data!.pageData, data!.layoutData, true, null, false)));
+                    controller.close();
+                    return;
+                }
+
                 const { body, head } = render(App, {
                     props: {
                         ssrMode: true,
@@ -301,6 +314,14 @@ export async function renderPageWithFormData(
 
     if (!data) return renderErrorPage(404, "Not Found", url, req);
 
+    if (!data.ssr) {
+        if (!data.csr && isDev) {
+            console.warn(`⚠️  ${url.pathname}: ssr=false && csr=false renders nothing — forcing csr=true`);
+        }
+        const html = buildHtml("", "", data.pageData, data.layoutData, true, formData, undefined, false);
+        return compress(html, "text/html; charset=utf-8", req, status);
+    }
+
     const { body, head } = render(App, {
         props: {
             ssrMode: true,

package/src/core/server.ts

@@ -72,7 +72,7 @@ const CORS_CONFIG: CorsConfig | null = _corsAllowedOrigins?.length
         allowedHeaders: splitCsvEnv("CORS_ALLOWED_HEADERS"),
         exposedHeaders: splitCsvEnv("CORS_EXPOSED_HEADERS"),
         credentials: process.env.CORS_CREDENTIALS === "true" || undefined,
-        maxAge: process.env.CORS_MAX_AGE ? parseInt(process.env.CORS_MAX_AGE, 10) : undefined,
+        maxAge: parseCorsMaxAge(process.env.CORS_MAX_AGE),
     }
     : null;
 
@@ -251,12 +251,21 @@ async function resolve(event: RequestEvent): Promise<Response> {
     if (method === "POST") {
         const pageMatch = findMatch(serverRoutes, path);
         if (pageMatch?.route.pageServer) {
+            // `use:enhance` sets this header — return JSON instead of re-rendering HTML
+            const isEnhanced = request.headers.get("x-bosia-action") === "1";
+
             try {
                 const mod = await pageMatch.route.pageServer();
                 if (mod.actions && typeof mod.actions === "object") {
                     const actionName = parseActionName(url);
                     const action = mod.actions[actionName];
                     if (!action) {
+                        if (isEnhanced) {
+                            return Response.json(
+                                { type: "error", status: 404, message: `Action "${actionName}" not found` },
+                                { status: 404 },
+                            );
+                        }
                         return renderErrorPage(404, `Action "${actionName}" not found`, url, request);
                     }
 
@@ -266,12 +275,21 @@ async function resolve(event: RequestEvent): Promise<Response> {
                         result = await action(event);
                     } catch (err) {
                         if (err instanceof Redirect) {
+                            if (isEnhanced) {
+                                return Response.json({ type: "redirect", status: 303, location: err.location });
+                            }
                             return new Response(null, {
                                 status: 303,
                                 headers: { Location: err.location },
                             });
                         }
                         if (err instanceof HttpError) {
+                            if (isEnhanced) {
+                                return Response.json(
+                                    { type: "error", status: err.status, message: err.message },
+                                    { status: err.status },
+                                );
+                            }
                             return renderErrorPage(err.status, err.message, url, request);
                         }
                         throw err;
@@ -279,6 +297,9 @@ async function resolve(event: RequestEvent): Promise<Response> {
 
                     // Redirect returned (not thrown)
                     if (result instanceof Redirect) {
+                        if (isEnhanced) {
+                            return Response.json({ type: "redirect", status: 303, location: result.location });
+                        }
                         return new Response(null, {
                             status: 303,
                             headers: { Location: result.location },
@@ -287,24 +308,48 @@ async function resolve(event: RequestEvent): Promise<Response> {
 
                     // ActionFailure — re-render with failure status
                     if (result instanceof ActionFailure) {
+                        if (isEnhanced) {
+                            return Response.json(
+                                { type: "failure", status: result.status, data: result.data },
+                                { status: result.status },
+                            );
+                        }
                         return renderPageWithFormData(url, locals, request, cookies, result.data, result.status);
                     }
 
                     // Success — re-render page with action return data
+                    if (isEnhanced) {
+                        return Response.json({ type: "success", status: 200, data: result ?? null });
+                    }
                     return renderPageWithFormData(url, locals, request, cookies, result ?? null, 200);
                 }
             } catch (err) {
                 if (err instanceof Redirect) {
+                    if (isEnhanced) {
+                        return Response.json({ type: "redirect", status: 303, location: err.location });
+                    }
                     return new Response(null, {
                         status: 303,
                         headers: { Location: err.location },
                     });
                 }
                 if (err instanceof HttpError) {
+                    if (isEnhanced) {
+                        return Response.json(
+                            { type: "error", status: err.status, message: err.message },
+                            { status: err.status },
+                        );
+                    }
                     return renderErrorPage(err.status, err.message, url, request);
                 }
                 if (isDev) console.error("Form action error:", err);
                 else console.error("Form action error:", (err as Error).message ?? err);
+                if (isEnhanced) {
+                    return Response.json(
+                        { type: "error", status: 500, message: "Internal Server Error" },
+                        { status: 500 },
+                    );
+                }
                 return Response.json({ error: "Internal Server Error" }, { status: 500 });
             }
         }
@@ -377,6 +422,20 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
     }
 }
 
+// ─── CORS Max Age ─────────────────────────────────────────
+
+function parseCorsMaxAge(value?: string): number | undefined {
+    if (!value) return undefined;
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`Invalid CORS_MAX_AGE: "${value}" — must be a non-negative integer (seconds)`);
+    }
+    const n = parseInt(value, 10);
+    if (!Number.isFinite(n) || n > Number.MAX_SAFE_INTEGER) {
+        throw new Error(`Invalid CORS_MAX_AGE: "${value}" — must be a non-negative integer (seconds)`);
+    }
+    return n;
+}
+
 // ─── Body Size Limit ──────────────────────────────────────
 // Parsed once at startup from BODY_SIZE_LIMIT env var.
 // Format: "512K", "1M", "1G", plain bytes, or "Infinity".

package/src/lib/client.ts

@@ -0,0 +1,12 @@
+// ─── Bosia Client API ─────────────────────────────────────
+// Client-only helpers — import from "bosia/client".
+// Kept separate from "bosia" because these modules transitively
+// reference the bundler-virtual `bosia:routes` module and runtime
+// `window`, which break server-side imports (e.g. `+page.server.ts`
+// loaded directly by the prerenderer).
+//
+// Usage in user apps:
+//   import { enhance } from "bosia/client";
+
+export { enhance } from "../core/client/enhance.ts";
+export type { SubmitFunction, ActionResult } from "../core/client/enhance.ts";