bosia 0.8.16 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "0.8.16",
+	"version": "0.9.1",
 	"type": "module",
 	"description": "A fast, batteries-included fullstack framework — SSR · Svelte 5 Runes · Bun · ElysiaJS. File-based routing No Node.js, no Vite, no adapters.",
 	"keywords": [

package/src/core/appBase.ts

@@ -0,0 +1,25 @@
+import { normalizeBase } from "./basePath.ts";
+
+// The mounted base, resolved from whichever side of the wire is asking. Kept
+// out of paths.ts because that module reaches for `fs`, and this one has to
+// survive being pulled into a client bundle by `errors.ts`.
+//
+// Memoized on first use rather than at import: the CLI sets `BASE_PATH` after
+// these modules are already loaded, and tests need to move it between cases.
+let cached: string | null = null;
+
+export function currentBase(): string {
+	if (cached === null) {
+		cached = normalizeBase(
+			typeof window !== "undefined"
+				? (window as unknown as { __BOSIA_BASE__?: string }).__BOSIA_BASE__
+				: process.env.BASE_PATH,
+		);
+	}
+	return cached;
+}
+
+/** Test seam — the base is memoized per process. */
+export function resetBaseCache(): void {
+	cached = null;
+}

package/src/core/appHtml.ts

@@ -2,6 +2,8 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join, dirname } from "path";
 
 import { OUT_DIR } from "./paths.ts";
+import { rebaseHtmlAttrs } from "./basePath.ts";
+import { currentBase } from "./appBase.ts";
 
 // ─── Types ────────────────────────────────────────────────
 
@@ -128,5 +130,9 @@ export function interpolateSegment(
 		result = result.replaceAll("%bosia.nonce%", vars.nonce);
 	}
 
-	return result;
+	// src/app.html is app-authored markup like any other, so a font preload or a
+	// favicon written as href="/fonts/…" gets rebased here too. Without this it is
+	// the one URL that still escapes the mount, and it fails silently: the page
+	// renders, just with the fallback font.
+	return rebaseHtmlAttrs(currentBase(), result);
 }

package/src/core/basePath.ts

@@ -0,0 +1,128 @@
+// Mounting an app under a URL prefix — `BASE_PATH=/sso` serves the whole app
+// from https://host/sso/… instead of the origin root.
+//
+// Env-free and pure on purpose. The server reads `process.env.BASE_PATH`, the
+// browser reads `window.__BOSIA_BASE__`, and both call these same functions, so
+// the two halves of the router cannot drift apart. That matters more than it
+// looks: a mismatch means the server renders a page the client router then
+// fails to match, and the app hydrates into a blank screen.
+
+/** `""` for a root-mounted app, else a leading slash and no trailing one. */
+export function normalizeBase(raw: string | null | undefined): string {
+	const trimmed = (raw ?? "").trim().replace(/\/+$/, "");
+	if (!trimmed || trimmed === "/") return "";
+	return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+/**
+ * Prefix a root-absolute in-app path. Everything else is returned untouched — a
+ * full URL, a protocol-relative `//host`, a relative path, and a path already
+ * under the base, which makes this safe to apply twice.
+ *
+ * The last clause needs the `/` in `${base}/`: without it a base of `/sso` would
+ * swallow a sibling route `/sso-admin`. It does mean an app mounted at `/sso`
+ * that also has its own `/sso/…` route gets left alone — pathological, and the
+ * alternative is a prefix that is not idempotent.
+ */
+export function withBase(base: string, path: string): string {
+	if (!base || !path.startsWith("/") || path.startsWith("//")) return path;
+	if (path === base || path.startsWith(`${base}/`)) return path;
+	return base + path;
+}
+
+/**
+ * The in-app pathname for an incoming request, or `null` when the request is
+ * not ours to answer. `/sso` and `/sso/` both resolve to `/` so the root route
+ * is reachable with or without the trailing slash.
+ */
+export function stripBase(base: string, pathname: string): string | null {
+	if (!base) return pathname;
+	if (pathname === base) return "/";
+	if (pathname.startsWith(`${base}/`)) return pathname.slice(base.length);
+	return null;
+}
+
+// Root-absolute URLs in the attributes a browser resolves against the origin.
+// `(?!\/)` keeps protocol-relative `//host` out of it.
+const ROOT_ABSOLUTE_ATTR = /\b(href|src|action|formaction)=("|')(\/(?!\/)[^"']*)\2/gi;
+
+// CSS `url(/…)`, which reaches the origin exactly like an href does. Lives in
+// `style` attributes (where the quotes arrive HTML-escaped as `"`) and in
+// `<style>` blocks. A mask-image that silently 404s is a blank icon, not an
+// error, so this one is easy to miss.
+const CSS_URL_ROOT = /(url\(\s*(?:&quot;|&#39;|&apos;|["'])?)(\/(?!\/)[^)"'&\s]*)/gi;
+
+// Responsive image candidates. Each is "url" plus an optional `2x` / `640w`
+// descriptor, comma-separated, so the value needs splitting before `withBase`
+// can see a path.
+const SRCSET_ATTR = /\b(srcset|imagesrcset)=("|')([^"']*)\2/gi;
+
+// Leading whitespace + the url token of one candidate; the descriptor that may
+// follow is left exactly as written.
+const SRCSET_CANDIDATE = /^(\s*)(\S+)/;
+
+/**
+ * Rebase every candidate url in one `srcset` value.
+ *
+ * A `data:` URI can contain commas of its own (base64 padding aside, any
+ * `text/plain,a,b` does), and splitting on those would shred it. Nothing
+ * root-absolute can live inside a data URI anyway, so the whole value is left
+ * alone when one appears — split on top-level commas only if an app ever mixes
+ * a data URI with a root-absolute candidate in the same attribute.
+ */
+function rebaseSrcset(base: string, value: string): string {
+	if (value.includes("data:")) return value;
+	return value
+		.split(",")
+		.map((candidate) =>
+			candidate.replace(
+				SRCSET_CANDIDATE,
+				(_m, space: string, url: string) => space + withBase(base, url),
+			),
+		)
+		.join(",");
+}
+
+/**
+ * Rewrite root-absolute `href`/`src`/`action`/`srcset` in rendered markup so an
+ * app that writes `<a href="/masuk">` keeps working under a base with no code
+ * change.
+ *
+ * Only ever called on the SSR'd body and head, never on the JSON data islands —
+ * those carry loader output, and a blind rewrite there would corrupt any string
+ * that merely looked like a path.
+ */
+export function rebaseHtmlAttrs(base: string, html: string): string {
+	if (!base) return html;
+	return rebaseCssUrls(
+		base,
+		html
+			.replace(
+				ROOT_ABSOLUTE_ATTR,
+				(_match, attr: string, quote: string, path: string) =>
+					`${attr}=${quote}${withBase(base, path)}${quote}`,
+			)
+			.replace(
+				SRCSET_ATTR,
+				(_match, attr: string, quote: string, value: string) =>
+					`${attr}=${quote}${rebaseSrcset(base, value)}${quote}`,
+			),
+	);
+}
+
+/**
+ * The same `url(/…)` rewrite for a standalone stylesheet.
+ *
+ * A `@font-face` src or a `mask-image` inside a compiled .css file is out of
+ * reach of any markup rewrite — the browser resolves it against the origin, and
+ * a miss is silent: the wrong font renders, an icon is simply blank. Applied at
+ * build time, which is why a build and the server that runs it must agree on
+ * BASE_PATH.
+ */
+export function rebaseCssUrls(base: string, css: string): string {
+	if (!base) return css;
+	return css.replace(
+		CSS_URL_ROOT,
+		(_match, open: string, path: string) => `${open}${withBase(base, path)}`,
+	);
+}

package/src/core/build.ts

@@ -11,6 +11,7 @@ import { prerenderStaticRoutes, generateStaticSite } from "./prerender.ts";
 import { loadEnv, classifyEnvVars } from "./env.ts";
 import { generateEnvModules } from "./envCodegen.ts";
 import { BOSIA_NODE_PATH, OUT_DIR, resolveBosiaBin } from "./paths.ts";
+import { currentBase } from "./appBase.ts";
 import { finalizeTailwindCss, TW_TEMP_BASENAME } from "./twHash.ts";
 import { loadPlugins } from "./config.ts";
 import type { BuildContext } from "./types/plugin.ts";
@@ -276,6 +277,9 @@ const distManifest = {
 		"hydrate.js",
 	serverEntry,
 	tw: twFile,
+	// The CSS urls and the client route table are baked in with this prefix.
+	// Stamped so the server can warn when it boots with a different one.
+	basePath: currentBase(),
 };
 writeFileSync(`${OUT_DIR}/manifest.json`, JSON.stringify(distManifest, null, 2));
 console.log(`✅ Client bundle: ${jsFiles.join(", ")}`);

package/src/core/client/base.ts

@@ -0,0 +1,15 @@
+import { currentBase } from "../appBase.ts";
+
+/**
+ * The prefix this app is mounted under, handed over by the inline script
+ * `buildHtml` emits. `""` for a root-mounted app.
+ *
+ * The navigation path does not use this. `clientRoutes` are generated with the
+ * prefix already in them, so an anchor's href, the address bar and the route
+ * table are all the same strings — a click pushes exactly the URL that was in
+ * the link, and nothing rewrites a path after the user acts on it.
+ *
+ * It is needed only to build the `/__bosia/data` and `/__bosia/sse` URLs, where
+ * the mount prefix sits in front of the endpoint rather than in front of the route.
+ */
+export const base: string = currentBase();

package/src/core/client/hydrate.ts

@@ -7,6 +7,7 @@ import { clientRoutes } from "bosia:routes";
 import { appState } from "./appState.svelte.ts";
 import { captureSnapshot, liveContext, type CacheEntry } from "./loaderCache.ts";
 import type { LoaderDeps } from "../hooks.ts";
+import { base } from "./base.ts";
 
 // Pre-compile route patterns into RegExp at startup (shared by App.svelte and router via module reference)
 compileRoutes(clientRoutes);
@@ -182,7 +183,7 @@ if (process.env.NODE_ENV !== "production") {
 	let retryDelay = 1000;
 
 	function connectSSE() {
-		const es = new EventSource("/__bosia/sse");
+		const es = new EventSource(`${base}/__bosia/sse`);
 
 		es.addEventListener("reload", () => {
 			console.log("[Bosia] Reloading...");

package/src/core/client/prefetch.ts

@@ -6,6 +6,7 @@ import { findMatch } from "../matcher.ts";
 import { clientRoutes } from "bosia:routes";
 import { appState } from "./appState.svelte.ts";
 import { liveContext, shouldRerun } from "./loaderCache.ts";
+import { base } from "./base.ts";
 
 /**
  * Build the `_invalidated` mask bits for a target path using the current
@@ -77,7 +78,12 @@ export function dataUrl(path: string, invalidatedBits?: string): string {
 		const sep = qs ? "&" : "?";
 		qs = `${qs}${sep}_invalidated=${invalidatedBits}`;
 	}
-	return `/__bosia/data${p || "/index"}.json${qs}`;
+	// The one place a path is still taken apart, and it is URL construction rather
+	// than navigation: the data endpoint is `<base>/__bosia/data` + the *app* path,
+	// so the mount prefix moves from the front of the route to the front of the
+	// endpoint. Nothing the user sees passes through here.
+	if (base && (p === base || p.startsWith(`${base}/`))) p = p.slice(base.length);
+	return `${base}/__bosia/data${p || "/index"}.json${qs}`;
 }
 
 export const prefetchCache = new Map<string, { data: any; ts: number }>();

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

@@ -5,6 +5,13 @@
 import { findMatch, canonicalPathname } from "../matcher.ts";
 import { clientRoutes } from "bosia:routes";
 import { fireBeforeNavigate, type Navigation } from "./navListeners.ts";
+import { base } from "./base.ts";
+import { withBase } from "../basePath.ts";
+
+// Everything here is a real browser path, base and all. Under a BASE_PATH mount
+// the generated `clientRoutes` carry the prefix too, so an anchor's href, the
+// address bar and the route table are all already in the same space — a click
+// pushes exactly the URL that was in the link, untouched.
 
 export type NavType = "link" | "goto" | "popstate" | "form" | "enter";
 
@@ -93,6 +100,19 @@ export const router = new (class Router {
 		const pathname = path.split("?")[0].split("#")[0];
 		const match = findMatch(clientRoutes, pathname);
 		if (!match) {
+			// Every nav — goto, link, form — falls through here before leaving the
+			// app. Under a mount, a path that would have matched *with* the prefix is
+			// an app-space path handed to goto(); warn instead of rewriting, since the
+			// shipped design is that the router converts nothing.
+			if (
+				process.env.NODE_ENV !== "production" &&
+				base &&
+				findMatch(clientRoutes, withBase(base, pathname))
+			) {
+				console.warn(
+					`[bosia] "${path}" matched no route and is leaving the app — it is mounted at "${base}". Use "${withBase(base, path)}".`,
+				);
+			}
 			window.location.href = path;
 			return;
 		}

package/src/core/cookies.ts

@@ -1,4 +1,5 @@
 import type { Cookies, CookieOptions } from "./hooks.ts";
+import { currentBase } from "./appBase.ts";
 
 // ─── Cookie Validation (RFC 6265) ────────────────────────
 /** Rejects characters that could inject into Set-Cookie headers. */
@@ -25,7 +26,9 @@ const VALID_COOKIE_NAME = /^[!#$%&'*+\-.0-9A-Z^_`a-z|~]+$/;
 // ─── Cookie Defaults ─────────────────────────────────────
 /** Secure defaults matching SvelteKit conventions. */
 const COOKIE_DEFAULTS: CookieOptions = {
-	path: "/",
+	// `path` is deliberately absent: it is resolved per-jar in the constructor,
+	// because the base has to be read after the env is in place rather than
+	// whenever this module happens to be imported.
 	httpOnly: true,
 	secure: true,
 	sameSite: "Lax",
@@ -69,7 +72,11 @@ export class CookieJar implements Cookies {
 		this._isHttps = isHttps;
 		// Browsers drop Secure cookies sent over HTTP — only default `secure` on
 		// when the current request actually arrived over HTTPS.
-		this._defaults = isHttps ? COOKIE_DEFAULTS : { ...COOKIE_DEFAULTS, secure: false };
+		// Scoped to the mount, not the origin. Under BASE_PATH this is what keeps a
+		// session cookie out of the sibling apps sharing the host — and stops two
+		// bosia apps on one origin from overwriting each other's `session`.
+		const path = currentBase() || "/";
+		this._defaults = { ...COOKIE_DEFAULTS, path, secure: isHttps };
 	}
 
 	private get _incoming(): Record<string, string> {

package/src/core/env.ts

@@ -6,6 +6,7 @@ import { join } from "path";
 const FRAMEWORK_VARS = new Set([
 	"PORT",
 	"NODE_ENV",
+	"BASE_PATH",
 	"BODY_SIZE_LIMIT",
 	"CSRF_ALLOWED_ORIGINS",
 	"CSRF_EXEMPT_PATHS",

package/src/core/errors.ts

@@ -1,6 +1,9 @@
 // ─── Error / Redirect Helpers ────────────────────────────
 // Throw these from load() functions; the server catches and handles them.
 
+import { withBase } from "./basePath.ts";
+import { currentBase } from "./appBase.ts";
+
 export class HttpError extends Error {
 	constructor(
 		public status: number,
@@ -23,6 +26,12 @@ export class Redirect {
 		options?: RedirectOptions,
 	) {
 		validateRedirectLocation(location, options);
+		// Validate first, then rebase: the checks above are about what the app
+		// asked for, and a base prefix must never turn a rejected target into an
+		// accepted one. Every redirect() in every app funnels through here, which
+		// is the only reason mounting under a base needs no app change — an app
+		// writing redirect(303, "/masuk") gets /sso/masuk on the wire.
+		this.location = withBase(currentBase(), location);
 	}
 }
 

package/src/core/html.ts

@@ -2,6 +2,8 @@ import { existsSync, readFileSync } from "fs";
 import { getDeclaredEnvKeys } from "./env.ts";
 import { nonceAttr } from "./csp.ts";
 import { OUT_DIR } from "./paths.ts";
+import { rebaseHtmlAttrs } from "./basePath.ts";
+import { currentBase } from "./appBase.ts";
 import type { AppHtmlSegments } from "./appHtml.ts";
 import { interpolateSegment } from "./appHtml.ts";
 
@@ -9,7 +11,13 @@ import { interpolateSegment } from "./appHtml.ts";
 // Maps hashed filenames → script/link tags.
 // Cached at startup; server restarts on rebuild in dev anyway.
 
-export const distManifest: { js: string[]; css: string[]; entry: string; tw?: string } = (() => {
+export const distManifest: {
+	js: string[];
+	css: string[];
+	entry: string;
+	tw?: string;
+	basePath?: string;
+} = (() => {
 	const p = `${OUT_DIR}/manifest.json`;
 	return existsSync(p)
 		? JSON.parse(readFileSync(p, "utf-8"))
@@ -19,12 +27,32 @@ export const distManifest: { js: string[]; css: string[]; entry: string; tw?: st
 export const isDev = process.env.NODE_ENV !== "production";
 const cacheBust = isDev ? `?v=${Date.now()}` : "";
 
+// Every URL the framework itself emits into the document, prefixed once here so
+// mounting under a BASE_PATH is not thirteen separate string edits. All four are
+// "" + the original path when no base is set.
+const B = currentBase();
+const DIST = `${B}/dist/client`;
+const TW_CSS = `${B}/bosia-tw.css`;
+const FAVICON = `${B}/favicon.svg`;
+const SSE = `${B}/__bosia/sse`;
+
+/**
+ * Handed to the client bundle so its router strips the same prefix the server
+ * added. Emitted before the module script, and omitted entirely at the origin
+ * root so a root-mounted app carries no extra bytes.
+ */
+export function baseScript(nonce?: string): string {
+	return B
+		? `\n  <script${nonceAttr(nonce)}>window.__BOSIA_BASE__=${JSON.stringify(B)};</script>`
+		: "";
+}
+
 /** Tailwind stylesheet link. Content-hashed name needs no cache buster — the
  *  hash IS the buster. Fallback keeps older dist/ artifacts (no `tw` field) styled. */
 function twCssLink(): string {
 	return distManifest.tw
-		? `<link rel="stylesheet" href="/dist/client/${distManifest.tw}">`
-		: `<link rel="stylesheet" href="/bosia-tw.css${cacheBust}">`;
+		? `<link rel="stylesheet" href="${DIST}/${distManifest.tw}">`
+		: `<link rel="stylesheet" href="${TW_CSS}${cacheBust}">`;
 }
 
 /** Inline theme bootstrap — runs before paint to avoid FOUC. theme ∈ light|dark|system (missing = system). */
@@ -116,8 +144,15 @@ export function buildHtml(
 	bodyEndExtras?: string[],
 	segments?: AppHtmlSegments,
 ): string {
+	// An app writes <a href="/masuk">; under a base the browser has to be handed
+	// /sso/masuk or it walks off this app entirely. Only the rendered markup is
+	// touched — never the JSON data islands below, whose strings are loader
+	// output and would be corrupted by a path rewrite.
+	body = rebaseHtmlAttrs(B, body);
+	head = rebaseHtmlAttrs(B, head);
+
 	const cssLinks = (distManifest.css ?? [])
-		.map((f: string) => `<link rel="stylesheet" href="/dist/client/${f}">`)
+		.map((f: string) => `<link rel="stylesheet" href="${DIST}/${f}">`)
 		.join("\n  ");
 
 	const fallbackTitle = head.includes("<title>") ? "" : "<title>Bosia App</title>";
@@ -147,9 +182,9 @@ export function buildHtml(
 		: "";
 
 	const scripts = csr
-		? `${envScript}${dataIslands}${sysScript}\n  <script${n} type="module" src="/dist/client/${distManifest.entry}${cacheBust}"></script>`
+		? `${baseScript(nonce)}${envScript}${dataIslands}${sysScript}\n  <script${n} type="module" src="${DIST}/${distManifest.entry}${cacheBust}"></script>`
 		: isDev
-			? `\n  <script${n}>!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>`
+			? `\n  <script${n}>!function r(){var e=new EventSource("${SSE}");e.addEventListener("reload",()=>location.reload());e.onopen=()=>r._ok||(r._ok=1);e.onerror=()=>{e.close();setTimeout(r,2000)}}()</script>`
 			: "";
 
 	const bodyEnd = bodyEndExtras?.length ? "\n  " + bodyEndExtras.join("\n  ") : "";
@@ -164,7 +199,7 @@ export function buildHtml(
 		const tailInterpolated = interpolateSegment(segments.tail, { nonce });
 		const faviconLine = segments.hasCustomFavicon
 			? ""
-			: `  <link rel="icon" type="image/svg+xml" href="/favicon.svg">\n`;
+			: `  <link rel="icon" type="image/svg+xml" href="${FAVICON}">\n`;
 
 		return (
 			headOpenInterpolated +
@@ -185,7 +220,7 @@ export function buildHtml(
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   ${fallbackTitle}
-  <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  <link rel="icon" type="image/svg+xml" href="${FAVICON}">
   ${head}
   ${cssLinks}
   ${twCssLink()}
@@ -210,20 +245,20 @@ export function buildHtmlShellOpen(
 	const key = safeLang(lang);
 	const n = nonceAttr(nonce);
 	const cssLinks = (distManifest.css ?? [])
-		.map((f: string) => `<link rel="stylesheet" href="/dist/client/${f}">`)
+		.map((f: string) => `<link rel="stylesheet" href="${DIST}/${f}">`)
 		.join("\n  ");
 
 	if (segments) {
 		const headOpenInterpolated = interpolateSegment(segments.headOpen, { lang: key, nonce });
 		const faviconLine = segments.hasCustomFavicon
 			? ""
-			: `  <link rel="icon" type="image/svg+xml" href="/favicon.svg">\n`;
+			: `  <link rel="icon" type="image/svg+xml" href="${FAVICON}">\n`;
 		return (
 			headOpenInterpolated +
 			`\n  ${faviconLine}${cssLinks}\n` +
 			`  ${twCssLink()}\n` +
 			`  <script${n}>${THEME_INIT_JS}</script>\n` +
-			`  <link rel="modulepreload" href="/dist/client/${distManifest.entry}${cacheBust}">`
+			`  <link rel="modulepreload" href="${DIST}/${distManifest.entry}${cacheBust}">`
 		);
 	}
 
@@ -231,11 +266,11 @@ export function buildHtmlShellOpen(
 		`<!DOCTYPE html>\n<html lang="${key}">\n<head>\n` +
 		`  <meta charset="UTF-8">\n` +
 		`  <meta name="viewport" content="width=device-width, initial-scale=1.0">\n` +
-		`  <link rel="icon" type="image/svg+xml" href="/favicon.svg">\n` +
+		`  <link rel="icon" type="image/svg+xml" href="${FAVICON}">\n` +
 		`  ${cssLinks}\n` +
 		`  ${twCssLink()}\n` +
 		`  <script${n}>${THEME_INIT_JS}</script>\n` +
-		`  <link rel="modulepreload" href="/dist/client/${distManifest.entry}${cacheBust}">`
+		`  <link rel="modulepreload" href="${DIST}/${distManifest.entry}${cacheBust}">`
 	);
 }
 
@@ -290,7 +325,9 @@ export function buildMetadataChunk(
 		out += `</head>\n<body>\n${SPINNER}`;
 	}
 
-	return out;
+	// All markup, no data islands — safe to rebase wholesale, which is what picks
+	// up an app's own headExtras (a canonical link, an og:image on a local file).
+	return rebaseHtmlAttrs(B, out);
 }
 
 export function escapeHtml(s: string): string {
@@ -319,12 +356,17 @@ export function buildHtmlTail(
 	layoutDeps: any[] | null = null,
 	segments?: AppHtmlSegments,
 ): string {
+	// Same rebase as buildHtml — the streamed tail carries the identical markup.
+	body = rebaseHtmlAttrs(B, body);
+	head = rebaseHtmlAttrs(B, head);
+
 	const n = nonceAttr(nonce);
 	let out = `<script${n}>document.getElementById('__bs__').remove()</script>`;
 	out += `\n<div id="app">${body}</div>`;
 	if (head)
 		out += `\n<script${n}>document.head.insertAdjacentHTML('beforeend',${safeJsonStringify(head)})</script>`;
 	if (csr) {
+		out += baseScript(nonce);
 		const publicEnv = getPublicDynamicEnv();
 		if (Object.keys(publicEnv).length > 0) {
 			out += `\n<script${n}>window.__BOSIA_ENV__=${safeJsonStringify(publicEnv)};</script>`;
@@ -342,9 +384,9 @@ export function buildHtmlTail(
 		if (ssrFlag || depsInject) {
 			out += `\n<script${n}>${ssrFlag}${depsInject}</script>`;
 		}
-		out += `\n<script${n} type="module" src="/dist/client/${distManifest.entry}${cacheBust}"></script>`;
+		out += `\n<script${n} type="module" src="${DIST}/${distManifest.entry}${cacheBust}"></script>`;
 	} else if (isDev) {
-		out += `\n<script${n}>!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>`;
+		out += `\n<script${n}>!function r(){var e=new EventSource("${SSE}");e.addEventListener("reload",()=>location.reload());e.onopen=()=>r._ok||(r._ok=1);e.onerror=()=>{e.close();setTimeout(r,2000)}}()</script>`;
 	}
 	if (bodyEndExtras?.length) {
 		for (const fragment of bodyEndExtras) {

package/src/core/prerender.ts

@@ -4,6 +4,7 @@ import { join } from "path";
 import type { RouteManifest, TrailingSlash } from "./types.ts";
 
 import { BOSIA_NODE_PATH, OUT_DIR } from "./paths.ts";
+import { currentBase } from "./appBase.ts";
 
 /** Acquire an OS-assigned ephemeral port. Tiny TOCTOU race window; acceptable for build-time use. */
 export function getEphemeralPort(): Promise<number> {
@@ -184,7 +185,10 @@ export async function prerenderStaticRoutes(manifest: RouteManifest): Promise<vo
 	try {
 		// Poll /_health until ready (max 10s). Check first, sleep only on failure —
 		// avoids a guaranteed floor when the server is already up.
-		const base = `http://localhost:${port}`;
+		// The child inherits BASE_PATH, so it 404s anything outside the mount —
+		// including /_health. Prefix here and every fetch below follows; the files
+		// we write stay app-space, which is what the server looks them up by.
+		const base = `http://localhost:${port}${currentBase()}`;
 		let ready = false;
 		const deadline = Date.now() + 10_000;
 		while (Date.now() < deadline) {

package/src/core/routeFile.ts

@@ -1,5 +1,25 @@
 import { writeFileSync, mkdirSync } from "fs";
 import type { RouteManifest } from "./types.ts";
+import { currentBase } from "./appBase.ts";
+
+/**
+ * The pattern the *client* router matches against. It sees real browser URLs, so
+ * under a BASE_PATH mount the table has to carry the prefix — that is what lets
+ * `findMatch` take `location.pathname` and an anchor's href exactly as they are,
+ * with no conversion anywhere in the navigation path.
+ *
+ * `serverRoutes` deliberately does not get this: the server strips the prefix at
+ * the edge of the request, so hooks, `load()` and `event.url.pathname` keep
+ * seeing app-space paths and app code never has to know it is mounted.
+ *
+ * The root route maps to the bare base (`/sso`, not `/sso/`) so it agrees with
+ * the URL a browser actually lands on.
+ */
+function clientPattern(pattern: string): string {
+	const base = currentBase();
+	if (!base) return pattern;
+	return pattern === "/" ? base : base + pattern;
+}
 
 // ─── Route File Generator ─────────────────────────────────
 // Generates .bosia/routes.ts — ONE file with three exports:
@@ -69,7 +89,7 @@ export function generateRoutesFile(manifest: RouteManifest): void {
 			.map((id) => (id === null ? "null" : JSON.stringify(id)))
 			.join(", ");
 		lines.push("  {");
-		lines.push(`    pattern: ${JSON.stringify(r.pattern)},`);
+		lines.push(`    pattern: ${JSON.stringify(clientPattern(r.pattern))},`);
 		lines.push(`    page: () => import(${JSON.stringify(toImportPath(r.page))}),`);
 		lines.push(`    layouts: [${layoutImports}],`);
 		lines.push(`    errorPages: [${errorPageImports}],`);
@@ -202,7 +222,7 @@ function generateClientRoutesFile(
 			.map((id) => (id === null ? "null" : JSON.stringify(id)))
 			.join(", ");
 		lines.push("  {");
-		lines.push(`    pattern: ${JSON.stringify(r.pattern)},`);
+		lines.push(`    pattern: ${JSON.stringify(clientPattern(r.pattern))},`);
 		lines.push(`    page: () => import(${JSON.stringify(toImportPath(r.page))}),`);
 		lines.push(`    layouts: [${layoutImports}],`);
 		lines.push(`    errorPages: [${errorPageImports}],`);

package/src/core/server.ts

@@ -21,9 +21,11 @@ import type { CsrfConfig } from "./csrf.ts";
 import { applyCorsVary, getCorsHeaders, handlePreflight } from "./cors.ts";
 import type { CorsConfig } from "./cors.ts";
 import { buildCspHeader, CSP_DIRECTIVES_TEMPLATE, CSP_ENABLED, generateNonce } from "./csp.ts";
-import { isDev, compress, isStaticPath } from "./html.ts";
+import { isDev, compress, isStaticPath, distManifest } from "./html.ts";
 import { dev500WithPlugins } from "./dev-500.ts";
 import { OUT_DIR } from "./paths.ts";
+import { stripBase, withBase } from "./basePath.ts";
+import { currentBase } from "./appBase.ts";
 import { pidsOnPort } from "./port.ts";
 import { buildPrerenderManifest, buildStaticManifest, lookupStatic } from "./staticManifest.ts";
 import { dedup } from "./dedup.ts";
@@ -158,6 +160,19 @@ if (CSP_DIRECTIVES_TEMPLATE) {
 	console.log(`🔒 CSP: opt-in header active`);
 }
 
+if (currentBase()) {
+	console.log(`📍 Mounted under ${currentBase()} (BASE_PATH)`);
+}
+
+// The CSS urls and the client route table are baked in at build time, so a
+// build and the server running it have to agree. Older dist/ artifacts carry no
+// `basePath` field — stay quiet for those rather than warn about nothing.
+if (distManifest.basePath !== undefined && distManifest.basePath !== currentBase()) {
+	console.warn(
+		`⚠️  Built for BASE_PATH="${distManifest.basePath}" but running with "${currentBase()}" — CSS urls and the client route table are baked in and will not match.`,
+	);
+}
+
 // ─── Core Request Resolver ────────────────────────────────
 // This is the inner handler that hooks wrap around.
 
@@ -632,7 +647,10 @@ async function resolve(event: RequestEvent): Promise<Response> {
 		if (canonical !== null) {
 			return new Response(null, {
 				status: 308,
-				headers: { Location: canonical + url.search + url.hash },
+				// `path` is app-space — the base came off at the top of handleRequest.
+				// This Location goes back to the browser, so it has to be put back on,
+				// or a `trailingSlash: "always"` route 308s every request off the mount.
+				headers: { Location: withBase(currentBase(), canonical) + url.search + url.hash },
 			});
 		}
 	}
@@ -864,6 +882,17 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 		if (fwdProto) url.protocol = `${fwdProto}:`;
 	}
 
+	// Mounted under BASE_PATH? Everything downstream — hooks, the router, the
+	// /_health and /__bosia tests below — works in app space, so the prefix comes
+	// off exactly once, here, before anything reads a pathname. A request that is
+	// not under the base was never this app's to answer.
+	const base = currentBase();
+	if (base) {
+		const appPath = stripBase(base, url.pathname);
+		if (appPath === null) return new Response("Not Found", { status: 404 });
+		url.pathname = appPath;
+	}
+
 	// Reject new non-health requests during shutdown
 	if (shuttingDown && url.pathname !== "/_health") {
 		return new Response("Service Unavailable", {

package/src/core/svelteCompiler.ts

@@ -2,6 +2,8 @@ import { compile, compileModule } from "svelte/compiler";
 import type { BunPlugin } from "bun";
 
 import { auditSvelteSource } from "./svelteAudit.ts";
+import { rebaseHtmlAttrs } from "./basePath.ts";
+import { currentBase } from "./appBase.ts";
 import { loadBosiaConfig } from "./config.ts";
 import type { StrictImportsOption } from "./types/plugin.ts";
 
@@ -61,6 +63,37 @@ function fixBindShadow(code: string): string {
 		.replace(/\bfunction set\(\$\$value\)/g, () => "function $$s($$value)");
 }
 
+// Under a BASE_PATH mount, a component's own `<a href="/masuk">` is the one URL
+// the server-side HTML rewrite cannot hold on to: the client re-renders on mount
+// and Svelte writes the original literal straight back into the DOM. Nothing
+// downstream saves it: the router converts nothing, so the href a crawler reads,
+// a middle-click opens, "copy link address" yields — and the click itself — all
+// point at the origin root, i.e. at whatever other app lives there.
+//
+// So the prefix is baked in at compile time instead. Only the markup is touched:
+// a root-absolute string inside <script> could be anything, and guessing is how
+// you corrupt an unrelated constant. Attribute interpolation survives, since the
+// rewrite only touches the leading literal — href="/user/{id}" is still valid.
+//
+// Dynamic values (href={someUrl}) are built in script and still need `base`.
+export function rebaseSvelteMarkup(source: string): string {
+	// currentBase(), not the paths.ts const: that one freezes at import, and this
+	// module is loaded long before a build sets the env.
+	const base = currentBase();
+	if (!base) return source;
+
+	const scripts: string[] = [];
+	const masked = source.replace(/<script[\s\S]*?<\/script>/gi, (block) => {
+		scripts.push(block);
+		return `<!--bosia:script:${scripts.length - 1}-->`;
+	});
+
+	return rebaseHtmlAttrs(base, masked).replace(
+		/<!--bosia:script:(\d+)-->/g,
+		(_match, index: string) => scripts[Number(index)],
+	);
+}
+
 export function makeBosiaSvelteCompiler(target: "browser" | "bun"): BunPlugin {
 	const generate = target === "browser" ? "client" : "server";
 	const dev = process.env.NODE_ENV !== "production";
@@ -75,7 +108,7 @@ export function makeBosiaSvelteCompiler(target: "browser" | "bun"): BunPlugin {
 
 			build.onLoad({ filter: /\.svelte$/ }, async (args) => {
 				const source = await Bun.file(args.path).text();
-				const result = compile(source, {
+				const result = compile(rebaseSvelteMarkup(source), {
 					generate,
 					css: target === "browser" ? "injected" : "external",
 					dev,

package/src/core/twHash.ts

@@ -1,5 +1,7 @@
-import { readFileSync, renameSync } from "fs";
+import { readFileSync, renameSync, writeFileSync } from "fs";
 import { join, dirname } from "path";
+import { rebaseCssUrls } from "./basePath.ts";
+import { currentBase } from "./appBase.ts";
 
 /** Temp filename Tailwind CLI writes to before the content-hash rename. */
 export const TW_TEMP_BASENAME = ".bosia-tw.build.css";
@@ -10,6 +12,20 @@ export const TW_TEMP_BASENAME = ".bosia-tw.build.css";
  * so it gets immutable caching). Returns the final basename.
  */
 export function finalizeTailwindCss(tempPath: string): string {
+	// Rebase before hashing, so the hash describes the bytes actually served. A
+	// @font-face src or mask-image written as url(/fonts/…) resolves against the
+	// origin and would land outside the mount — silently, as a fallback font or a
+	// blank icon rather than an error.
+	//
+	// Read here, not at import: build.ts calls loadEnv() after its imports, so a
+	// BASE_PATH that lives in .env.production is not in process.env yet when this
+	// module loads.
+	const base = currentBase();
+	if (base) {
+		const rebased = rebaseCssUrls(base, readFileSync(tempPath, "utf-8"));
+		writeFileSync(tempPath, rebased);
+	}
+
 	const bytes = readFileSync(tempPath);
 	const hash = new Bun.CryptoHasher("sha256").update(bytes).digest("hex").slice(0, 10);
 	const name = `bosia-tw-${hash}.css`;

package/src/lib/index.ts

@@ -8,6 +8,14 @@
 export { cn, getServerTime } from "./utils.ts";
 export { sequence, NO_FRAME_GUARD_HEADER } from "../core/hooks.ts";
 export { error, redirect, fail } from "../core/errors.ts";
+// `base` is the BASE_PATH the app is mounted under, "" at the origin root.
+// Almost nothing needs it: `redirect()` and every href in rendered markup are
+// rebased for you. It exists for the one case the framework cannot see — an
+// absolute URL an app builds by hand, e.g. `${url.origin}${base}/atur-sandi`
+// for a link that will be pasted somewhere else. `event.url.pathname` is app
+// space by the time a load() or action sees it, so never prepend it there.
+import { currentBase } from "../core/appBase.ts";
+export const base: string = currentBase();
 // `invalidate` / `invalidateAll` (server response-cache eviction) live in
 // "bosia/server" — they touch server-process state and pulling them into
 // the shared barrel leaks `process.env` reads into client bundles.