bosia 0.8.16 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "0.8.16",
+	"version": "0.9.0",
 	"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,94 @@
+// 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;
+
+/**
+ * Rewrite root-absolute `href`/`src`/`action` 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.
+ *
+ * Does not touch `srcset` — comma-separated candidates with descriptors, and
+ * nothing in the framework emits one root-absolute. An app that does needs
+ * `base` from "bosia".
+ */
+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}`,
+		),
+	);
+}
+
+/**
+ * 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/client/base.ts

@@ -0,0 +1,19 @@
+import { normalizeBase } from "../basePath.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` endpoint URL, where the mount
+ * prefix sits in front of the endpoint rather than in front of the route.
+ */
+export const base: string = normalizeBase(
+	typeof window !== "undefined"
+		? (window as unknown as { __BOSIA_BASE__?: string }).__BOSIA_BASE__
+		: "",
+);

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

@@ -6,6 +6,11 @@ import { findMatch, canonicalPathname } from "../matcher.ts";
 import { clientRoutes } from "bosia:routes";
 import { fireBeforeNavigate, type Navigation } from "./navListeners.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";
 
 function buildTarget(path: string): { url: URL; params: Record<string, string> } | null {

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

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync } from "fs";
 import { getDeclaredEnvKeys } from "./env.ts";
 import { nonceAttr } from "./csp.ts";
-import { OUT_DIR } from "./paths.ts";
+import { BASE_PATH, OUT_DIR } from "./paths.ts";
+import { rebaseHtmlAttrs } from "./basePath.ts";
 import type { AppHtmlSegments } from "./appHtml.ts";
 import { interpolateSegment } from "./appHtml.ts";
 
@@ -19,12 +20,31 @@ 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 DIST = `${BASE_PATH}/dist/client`;
+const TW_CSS = `${BASE_PATH}/bosia-tw.css`;
+const FAVICON = `${BASE_PATH}/favicon.svg`;
+const SSE = `${BASE_PATH}/__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 BASE_PATH
+		? `\n  <script${nonceAttr(nonce)}>window.__BOSIA_BASE__=${JSON.stringify(BASE_PATH)};</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 +136,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(BASE_PATH, body);
+	head = rebaseHtmlAttrs(BASE_PATH, 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 +174,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 +191,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 +212,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 +237,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 +258,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 +317,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(BASE_PATH, out);
 }
 
 export function escapeHtml(s: string): string {
@@ -319,12 +348,17 @@ export function buildHtmlTail(
 	layoutDeps: any[] | null = null,
 	segments?: AppHtmlSegments,
 ): string {
+	// Same rebase as buildHtml — the streamed tail carries the identical markup.
+	body = rebaseHtmlAttrs(BASE_PATH, body);
+	head = rebaseHtmlAttrs(BASE_PATH, 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 +376,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/paths.ts

@@ -1,5 +1,6 @@
 import { join, dirname } from "path";
 import { existsSync } from "fs";
+import { normalizeBase } from "./basePath.ts";
 
 // This file lives at src/core/paths.ts → package root is ../..
 const BOSIA_PKG_DIR = join(import.meta.dir, "..", "..");
@@ -33,6 +34,15 @@ export const BOSIA_NODE_PATH = ALL_NM.join(":");
 // `bun run build` (./dist) don't clobber each other.
 export const OUT_DIR = process.env.BOSIA_OUT_DIR ?? "./dist";
 
+/**
+ * URL prefix the whole app is mounted under — `""` (origin root) unless
+ * `BASE_PATH` says otherwise. Read once here so every consumer agrees; the
+ * browser half gets the same value through `window.__BOSIA_BASE__`.
+ *
+ * Server-only: this module reaches for `fs`, so it never enters a client bundle.
+ */
+export const BASE_PATH = normalizeBase(process.env.BASE_PATH);
+
 /** Find a binary from bosia's dependencies (handles hoisting) */
 export function resolveBosiaBin(name: string): string {
 	for (const nm of ALL_NM) {

package/src/core/prerender.ts

@@ -3,7 +3,7 @@ import { createServer } from "net";
 import { join } from "path";
 import type { RouteManifest, TrailingSlash } from "./types.ts";
 
-import { BOSIA_NODE_PATH, OUT_DIR } from "./paths.ts";
+import { BASE_PATH, BOSIA_NODE_PATH, OUT_DIR } from "./paths.ts";
 
 /** Acquire an OS-assigned ephemeral port. Tiny TOCTOU race window; acceptable for build-time use. */
 export function getEphemeralPort(): Promise<number> {
@@ -184,7 +184,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}${BASE_PATH}`;
 		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

@@ -23,7 +23,8 @@ 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 { dev500WithPlugins } from "./dev-500.ts";
-import { OUT_DIR } from "./paths.ts";
+import { BASE_PATH, OUT_DIR } from "./paths.ts";
+import { stripBase, withBase } from "./basePath.ts";
 import { pidsOnPort } from "./port.ts";
 import { buildPrerenderManifest, buildStaticManifest, lookupStatic } from "./staticManifest.ts";
 import { dedup } from "./dedup.ts";
@@ -158,6 +159,10 @@ if (CSP_DIRECTIVES_TEMPLATE) {
 	console.log(`🔒 CSP: opt-in header active`);
 }
 
+if (BASE_PATH) {
+	console.log(`📍 Mounted under ${BASE_PATH} (BASE_PATH)`);
+}
+
 // ─── Core Request Resolver ────────────────────────────────
 // This is the inner handler that hooks wrap around.
 
@@ -632,7 +637,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(BASE_PATH, canonical) + url.search + url.hash },
 			});
 		}
 	}
@@ -864,6 +872,16 @@ 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.
+	if (BASE_PATH) {
+		const appPath = stripBase(BASE_PATH, 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 { BASE_PATH } from "./paths.ts";
 
 /** Temp filename Tailwind CLI writes to before the content-hash rename. */
 export const TW_TEMP_BASENAME = ".bosia-tw.build.css";
@@ -10,6 +12,15 @@ 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.
+	if (BASE_PATH) {
+		const rebased = rebaseCssUrls(BASE_PATH, 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.