navgo 6.0.5 → 6.0.8

package/changelog.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## v6.0.8
+
+- breaking: make search-schema transitions atomic by publishing `router.route` before global `router.search_params`, with sync guard across both writes
+  - note: `router.route.subscribe(...)` now fires before `router.search_params` updates on search-schema transitions
+
+## v6.0.7
+
+- add `nav.status` as the formal HTTP-like status for completed navigations
+- add route-level `ssr = {serve_shell, refresh_every}` exports
+- add bidirectional `rewrite` hooks so apps can map public URLs to a canonical internal route tree and back again
+- add `router.href()` for building public in-app links from canonical internal targets
+- expose `internal_url`, `path`, and `context` on navigation targets, the route store, and loader/search hook contexts
+
+## v6.0.6
+
+- add `data.__meta.preloads` for executed LoadPlans so consumers can reuse same-origin request URLs
+  for SSR preload headers
+
 ## v6.0.5
 
 - fix hash-only back scroll restoration when a pending same-page hash click is cancelled before its `hashchange` settles
@@ -51,18 +69,18 @@ Before:
 ```js
 // manual orchestration (old style)
 const routes = [
-	[
-		'/dashboard',
-		{
-			async loader({ fetch }) {
-				const [user, posts] = await Promise.all([
-					fetch('/api/user').then(r => r.json()),
-					fetch('/api/posts?limit=10').then(r => r.json()),
-				])
-				return { user, posts }
-			},
-		},
-	],
+  [
+    '/dashboard',
+    {
+      async loader({ fetch }) {
+        const [user, posts] = await Promise.all([
+          fetch('/api/user').then(r => r.json()),
+          fetch('/api/posts?limit=10').then(r => r.json()),
+        ])
+        return { user, posts }
+      },
+    },
+  ],
 ]
 ```
 
@@ -71,17 +89,17 @@ After:
 ```js
 // LoadPlan
 const routes = [
-	[
-		'/dashboard',
-		{
-			loader() {
-				return {
-					user: '/api/user',
-					posts: { request: '/api/posts?limit=10', cache: { strategy: 'swr', ttl: 5_000 } },
-				}
-			},
-		},
-	],
+  [
+    '/dashboard',
+    {
+      loader() {
+        return {
+          user: '/api/user',
+          posts: { request: '/api/posts?limit=10', cache: { strategy: 'swr', ttl: 5_000 } },
+        }
+      },
+    },
+  ],
 ]
 ```
 
@@ -91,20 +109,20 @@ Layout/group loaders now run for every matched child. Read their data from
 Before:
 
 ```js
-const routes = [
-	['/account/:id', { loader: ctx => ctx.fetch('/api/account').then(r => r.json()) }],
-]
+const routes = [['/account/:id', { loader: ctx => ctx.fetch('/api/account').then(r => r.json()) }]]
 ```
 
 After:
 
 ```js
 const routes = [
-	{
-		layout: { default: 'AccountLayout' },
-		loader: async ctx => ctx.fetch('/api/session').then(r => r.json()),
-		routes: [['/account/:id', { loader: async ctx => ctx.fetch('/api/account').then(r => r.json()) }]],
-	},
+  {
+    layout: { default: 'AccountLayout' },
+    loader: async ctx => ctx.fetch('/api/session').then(r => r.json()),
+    routes: [
+      ['/account/:id', { loader: async ctx => ctx.fetch('/api/account').then(r => r.json()) }],
+    ],
+  },
 ]
 
 // in after_navigate:

package/index.d.ts

@@ -46,6 +46,14 @@ export interface LoadPlanDefaults {
 	cache?: CacheOptions
 }
 
+export type LoadPlanSource = 'network' | 'cache' | 'stale' | 'revalidated'
+
+export interface LoadPlanMeta {
+	source: Record<string, LoadPlanSource>
+	at: number
+	preloads?: string[]
+}
+
 export interface SearchOptions {
 	show_defaults?: boolean
 	debounce?: number
@@ -74,9 +82,28 @@ export interface SearchOptions {
 		  >)
 }
 
+export interface RewriteResult {
+	url?: string | URL
+	context?: unknown
+}
+
+export interface RewriteContext<T = unknown> {
+	url: URL
+	current: NavigationTarget<T> | null
+	context?: unknown
+}
+
+export interface Rewrite<T = unknown> {
+	input?(ctx: RewriteContext<T>): string | URL | RewriteResult | void
+	output?(ctx: RewriteContext<T>): string | URL | RewriteResult | void
+}
+
 export interface LoaderContext {
 	route_entry: RouteTuple
 	url: URL
+	internal_url: URL
+	path: string
+	context?: unknown
 	params: Params
 	search_params: Record<string, unknown>
 	signal: AbortSignal
@@ -93,7 +120,7 @@ export interface Match<T = unknown> {
 	layout?: any
 	/** Present when `type === 'route'`. */
 	route?: RouteTuple<T>
-	/** Loader result for this match when available (e.g. on navigation completion). */
+	/** Loader result for this match when available (e.g. on navigation completion). LoadPlan results include `__meta`. */
 	data?: unknown
 }
 
@@ -129,12 +156,19 @@ export interface PreloadBundle<T = unknown> {
 	data?: unknown
 }
 
+export interface SsrOptions {
+	serve_shell?: boolean
+	refresh_every?: number
+}
+
 /** Optional per-route hooks recognized by Navgo. */
 export interface Hooks {
 	/** Validate and/or coerce params (schema runs before coercer). */
 	param_rules?: Record<string, ParamRule>
 	/** Load data for a route before navigation. Return a LoadPlan (object) or a Promise for arbitrary data. */
 	loader?(ctx: LoaderContext): LoadPlan | Promise<unknown>
+	/** Optional SSR metadata exposed on completed navigations as `nav.ssr`. */
+	ssr?: SsrOptions
 	/** Predicate used during match(); may be async. If it returns `false`, the route is skipped. */
 	validate?(params: Params): boolean | Promise<boolean>
 	/** Route-level navigation guard, called on the current route when leaving it. Synchronous only; call `nav.cancel()` to prevent navigation. */
@@ -145,6 +179,9 @@ export interface Hooks {
 
 export interface NavigationTarget<T = unknown> {
 	url: URL
+	internal_url: URL
+	path: string
+	context?: unknown
 	params: Params
 	/** The matched route tuple from your original `routes` list; `null` when unmatched (e.g. external). */
 	route: RouteTuple<T> | null
@@ -152,7 +189,7 @@ export interface NavigationTarget<T = unknown> {
 	matches?: Match<T>[]
 	/** Keyed lookup into matched layout/group wrappers by `RouteGroup.id`. */
 	layouts?: LayoutsMap<T>
-	/** Optional data from route loader when available. */
+	/** Optional data from route loader when available. LoadPlan results include `__meta`. */
 	data?: unknown
 }
 
@@ -160,10 +197,14 @@ export interface Navigation {
 	type: 'link' | 'goto' | 'popstate' | 'leave'
 	from: NavigationTarget | null
 	to: NavigationTarget | null
+	/** HTTP-like status for the completed target. Unmatched routes are `404`; `data.__error.status` wins when present. */
+	status: number
 	will_unload: boolean
 	cancelled: boolean
 	/** The original browser event that initiated navigation, when available. */
 	event?: Event
+	/** Optional SSR metadata resolved from the matched leaf route's `ssr` export. */
+	ssr?: SsrOptions
 	cancel(): void
 }
 
@@ -194,6 +235,8 @@ export interface NavgoHistoryMeta {
 export interface Options {
 	/** App base path. Default '/' */
 	base?: string
+	/** Optional bidirectional URL rewrite hooks. */
+	rewrite?: Rewrite
 	/** Delay before hover preloading in milliseconds. Default 20. */
 	preload_delay?: number
 	/** Disable hover/touch preloading when `false`. Default true. */
@@ -203,7 +246,7 @@ export interface Options {
 	search?: SearchOptions
 	/** Global hook fired after per-route `before_route_leave`, before loader/history change. Can cancel. */
 	before_navigate?(nav: Navigation): void
-	/** Global hook fired after routing completes (data loaded, URL updated, handlers run). */
+	/** Global hook fired after routing completes (data loaded, URL updated, handlers run). `goto()` resolves after this hook. */
 	after_navigate?(nav: Navigation, on_revalidate?: (cb: () => void) => void): void | Promise<void>
 	/** Optional hook awaited after `after_navigate` and before scroll handling.
 	 *  Useful for UI frameworks (e.g., Svelte) to flush DOM updates so anchor/top
@@ -221,25 +264,39 @@ export interface Options {
 /** Navgo default export: class-based router. */
 export default class Navgo<T = unknown> {
 	constructor(routes?: Array<RouteEntry<T>>, opts?: Options)
-	/** Format `url` relative to the configured base. */
+	/** Format a public URL into the router's internal canonical path. */
 	format(url: string): string | false
+	/** Build a public in-app href from an internal or literal input target. */
+	href(
+		url: string | URL,
+		opts?: { absolute?: boolean; literal?: boolean; context?: unknown },
+	): string | false
 	/** SvelteKit-like navigation that runs `loader` before updating the URL. */
-	goto(url: string, opts?: { replace?: boolean }): Promise<void>
+	goto(
+		url: string | URL,
+		opts?: { replace?: boolean; literal?: boolean; context?: unknown },
+	): Promise<void>
 	/** Shallow push — updates URL/state without triggering handlers. */
 	push_state(url?: string | URL, state?: any): void
 	/** Shallow replace — updates URL/state without triggering handlers. */
 	replace_state(url?: string | URL, state?: any): void
 	/** Manually preload `loader` for a URL (deduped). */
-	preload(url: string): Promise<unknown | void>
+	preload(
+		url: string | URL,
+		opts?: { literal?: boolean; context?: unknown },
+	): Promise<unknown | void>
 	/** Try to match `url`; returns route tuple and params or `null`. Supports async `validate`. */
 	match(url: string): Promise<MatchResult<T> | null>
 	/** Attach history + click listeners and immediately process current location. */
 	init(): Promise<void>
 	/** Remove listeners installed by `init()`. */
 	destroy(): void
-	/** Writable store with current { url, route, params, matches, layouts, search_params }. */
+	/** Writable store with current { url, internal_url, path, context, route, params, matches, layouts, search_params }. */
 	readonly route: import('svelte/store').Writable<{
 		url: URL
+		internal_url: URL
+		path: string
+		context?: unknown
 		route: RouteTuple<T> | null
 		params: Params
 		matches: Match<T>[]

package/index.js

@@ -23,6 +23,7 @@ export default class Navgo {
 	/** @type {Options} */
 	#opts = {
 		base: '/',
+		rewrite: undefined,
 		preload_delay: 20,
 		preload_on_hover: true,
 		before_navigate: undefined,
@@ -51,9 +52,12 @@ export default class Navgo {
 	#base_rgx = /^\/+/
 	/** @type {Map<string, { promise?: Promise<PreloadBundle>, data?: PreloadBundle }>} */
 	#preloads = new Map()
-	/** @type {{ url: URL|null, route: RouteTuple|null, params: Params, matches: Match[], layouts: Record<string, Match>, search_params: Record<string, unknown> }} */
+	/** @type {{ url: URL|null, internal_url: URL|null, path: string, context: any, route: RouteTuple|null, params: Params, matches: Match[], layouts: Record<string, Match>, search_params: Record<string, unknown> }} */
 	#current = {
 		url: null,
+		internal_url: null,
+		path: '',
+		context: undefined,
 		route: null,
 		params: {},
 		matches: [],
@@ -86,6 +90,9 @@ export default class Navgo {
 	#search_writer = null
 	route = writable({
 		url: new URL(location.href),
+		internal_url: new URL(location.href),
+		path: normalize_path(new URL(location.href).pathname),
+		context: undefined,
 		route: null,
 		params: {},
 		matches: [],
@@ -108,7 +115,7 @@ export default class Navgo {
 		const url = new URL(info.href, location.href)
 
 		// Hash-only navigation on same path: let browser handle, but track index
-		if (url.hash && url.pathname === this.#current.url.pathname) {
+		if (url.hash && this.#same_public_url(url, this.#current.url)) {
 			const cur_hash = location.href.split('#')[1]
 			const next_hash = url.href.split('#')[1] ?? ''
 			if (cur_hash === next_hash) {
@@ -143,7 +150,7 @@ export default class Navgo {
 		})
 
 		ℹ('[🧭 link]', 'intercept', { href: info.href })
-		this.goto(info.href, { replace: false }, 'link', e)
+		this.goto(info.href, { replace: false, literal: true }, 'link', e)
 	}
 
 	#on_popstate = ev => {
@@ -154,10 +161,9 @@ export default class Navgo {
 		ℹ('[🧭 event:popstate]', st)
 		// Hash-only or state-only change: pathname+search unchanged -> skip loader
 		const cur = this.#current.url
-		const target = new URL(location.href)
-		if (cur && target.pathname === cur.pathname && target.search === cur.search) {
-			const next_current = { ...this.#current, url: target }
-			this.#current = next_current
+		const target = this.#resolve_url_and_path(location.href, { literal: true })
+		if (cur && target && this.#same_public_url(target.url, cur)) {
+			const next_current = this.#update_current_info(target)
 			ℹ('  - [🧭 event:popstate]', 'same path+search; skip loader')
 			this.#apply_scroll(ev)
 			this.route.set(next_current)
@@ -170,10 +176,9 @@ export default class Navgo {
 		// or after navigating to a different route and coming back via Back/Forward.
 		if (st?.shallow) {
 			const from = typeof st.from === 'string' ? st.from : null
-			if (!from || (cur && from === cur.pathname)) {
-				const next_current = { ...this.#current, url: target }
-				this.#current = next_current
-				this.#sync_search_from_url(target)
+			if (!from || (cur && normalize_path(from) === normalize_path(cur.pathname))) {
+				const next_current = this.#update_current_info(target)
+				this.#sync_search_from_url(next_current.url)
 				ℹ('  - [🧭 event:popstate]', 'shallow entry; skip loader')
 				this.#apply_scroll(ev)
 				this.route.set(next_current)
@@ -183,7 +188,7 @@ export default class Navgo {
 		}
 
 		ℹ('  - [🧭 event:popstate]', { idx: st?.idx })
-		this.goto(location.href, { replace: true }, 'popstate', ev)
+		this.goto(location.href, { replace: true, literal: true }, 'popstate', ev)
 	}
 	#on_hashchange = () => {
 		// if hashchange originated from a click we tracked, bump our index and persist it
@@ -221,8 +226,10 @@ export default class Navgo {
 			}
 		}
 		// update current URL snapshot and notify
-		this.#current.url = new URL(location.href)
-		this.route.set(this.#current)
+		const next_current = this.#update_current_info(
+			this.#resolve_url_and_path(location.href, { literal: true }),
+		)
+		this.route.set(next_current)
 		this.#update_active_links()
 	}
 
@@ -232,7 +239,7 @@ export default class Navgo {
 		const info = this.#link_from_event(ev, ev.type === 'mousedown')
 		if (info) {
 			ℹ('[🧭 preload]', 'link hover/tap', { href: info.href })
-			this.preload(info.href)
+			this.preload(info.href, { literal: true })
 		}
 	}
 	#mouse_move = ev => {
@@ -287,23 +294,180 @@ export default class Navgo {
 	//
 	// Helpers
 	//
+	#info(state) {
+		if (!state?.url) return null
+		const internal_url = state.internal_url || state.url
+		return {
+			url: state.url,
+			internal_url,
+			path: state.path || internal_url.pathname || '',
+			context: state.context,
+		}
+	}
+
+	#target(state, extra = undefined) {
+		const info = this.#info(state)
+		if (!info) return null
+		const target = {
+			...info,
+			params: state?.params || {},
+			route: state?.route || null,
+			matches: state?.matches || [],
+			layouts: state?.layouts || Object.create(null),
+		}
+		return extra ? { ...target, ...extra } : target
+	}
+
+	#update_current_info(info, fallback = location.href) {
+		this.#current = info
+			? { ...this.#current, ...this.#info(info) }
+			: { ...this.#current, url: new URL(fallback, location.href) }
+		return this.#current
+	}
+
+	#coerce_url(url_raw, base = location.href) {
+		if (url_raw == null) return new URL(location.href)
+		let raw = url_raw instanceof URL ? url_raw.href : String(url_raw)
+		const has_scheme = /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(raw)
+		const has_relative_prefix = /^(?:\/|\?|#|\.\/?|\.\.\/?)/.test(raw)
+		if (!has_scheme && !has_relative_prefix) raw = '/' + raw
+		return new URL(raw, base)
+	}
+
+	#public_key(url) {
+		return normalize_path(url.pathname) + (url.search || '')
+	}
+
+	#same_public_url(a, b) {
+		return !!a && !!b && this.#public_key(a) === this.#public_key(b)
+	}
+
+	#strip_base_path(pathname) {
+		const value = normalize_path(pathname)
+		const out = this.#base_rgx.test(value) && value.replace(this.#base_rgx, '/')
+		return out || false
+	}
+
+	#apply_base_path(pathname) {
+		const path = String(pathname || '/')
+		const out = path[0] === '/' ? path : '/' + path
+		if (this.#base == '/') return out
+		if (out === '/') return this.#base + '/'
+		return this.#base + out
+	}
+
+	#current_context(context = undefined) {
+		return context !== undefined
+			? context
+			: this.#current.context !== undefined
+				? this.#current.context
+				: this.#resolve_public_url(location.href)?.context
+	}
+
+	#resolved_info(url, internal_url = url, context = undefined) {
+		internal_url.pathname = normalize_path(internal_url.pathname)
+		return {
+			url,
+			internal_url,
+			path: internal_url.pathname,
+			load_key: this.#public_key(url),
+			context,
+		}
+	}
+
+	#apply_rewrite(kind, url, context = undefined) {
+		const fn = this.#opts.rewrite?.[kind]
+		if (typeof fn !== 'function') return { url, context }
+		try {
+			const out = fn({
+				url: new URL(url.href),
+				current: this.#target(this.#current),
+				context,
+			})
+			if (!out) return { url, context }
+			if (typeof out === 'string' || out instanceof URL) {
+				return { url: new URL(out, url), context }
+			}
+			return {
+				url: new URL(out.url ?? url, url),
+				context: out.context !== undefined ? out.context : context,
+			}
+		} catch (e) {
+			ℹ('[🧭 rewrite]', kind, 'error', { err: e })
+			return { url, context }
+		}
+	}
+
+	#resolve_public_url(url_raw) {
+		const url = this.#coerce_url(url_raw, location.href)
+		if (url.origin !== location.origin) return null
+		const stripped = this.#strip_base_path(url.pathname)
+		if (!stripped) return null
+		const internal_url = new URL(url.href)
+		internal_url.pathname = stripped
+		const rewritten = this.#apply_rewrite('input', internal_url)
+		return this.#resolved_info(url, rewritten.url, rewritten.context)
+	}
+
+	#resolve_internal_url(url_raw, context = undefined) {
+		const base =
+			this.#current.internal_url?.href ||
+			this.#resolve_public_url(location.href)?.internal_url?.href ||
+			location.href
+		const internal_url = this.#coerce_url(url_raw, base)
+		if (internal_url.origin !== location.origin) return null
+		internal_url.pathname = normalize_path(internal_url.pathname)
+		const rewritten = this.#apply_rewrite(
+			'output',
+			internal_url,
+			this.#current_context(context),
+		)
+		const url = rewritten.url
+		if (url.origin !== location.origin) return null
+		url.pathname = this.#apply_base_path(url.pathname)
+		return this.#resolved_info(url, internal_url, rewritten.context)
+	}
+
+	#resolve_url_and_path(url_raw, opts = {}) {
+		if (url_raw == null) return null
+		const raw = url_raw instanceof URL ? url_raw.href : String(url_raw)
+		const has_scheme = /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(raw)
+		const same_origin =
+			!has_scheme || this.#coerce_url(url_raw, location.href).origin === location.origin
+		const public_info = same_origin ? this.#resolve_public_url(url_raw) : null
+		if (opts.literal) return public_info
+		if (!same_origin) return null
+		const use_public =
+			!!public_info && public_info.path !== normalize_path(public_info.url.pathname)
+		const out = use_public ? public_info : this.#resolve_internal_url(url_raw, opts.context)
+		ℹ('[🧭 resolve]', {
+			url_in: url_raw,
+			mode: use_public ? 'public' : 'internal',
+			url: out?.url?.href,
+			internal_url: out?.internal_url?.href,
+			path: out?.path,
+			context: out?.context,
+		})
+		return out || public_info
+	}
+
 	/** @param {string} url @returns {string|false} */
 	format(url) {
 		if (!url) return url
-		url = normalize_path(url)
-		const out = this.#base_rgx.test(url) && url.replace(this.#base_rgx, '/')
-		ℹ('[🧭 format]', { in: url, out })
-		return out
+		const out = this.#resolve_public_url(url)
+		const value = out
+			? out.internal_url.pathname +
+				(out.internal_url.search || '') +
+				(out.internal_url.hash || '')
+			: false
+		ℹ('[🧭 format]', { in: url, out: value || false })
+		return value || false
 	}
-	#resolve_url_and_path(url_raw) {
-		if (url_raw == null) return null
-		if (typeof url_raw !== 'string') url_raw = String(url_raw)
-		if (url_raw[0] == '/' && !this.#base_rgx.test(url_raw)) url_raw = this.#base + url_raw
-		const url = new URL(url_raw, location.href)
-		const path = this.format(url.pathname).match?.(/[^?#]*/)?.[0]
-		const load_key = path && path + url.search
-		ℹ('[🧭 resolve]', { url_in: url_raw, url: url.href, path })
-		return path ? { url, path, load_key } : null
+
+	href(url_raw = location.href, opts = {}) {
+		const info = this.#resolve_url_and_path(url_raw, opts)
+		if (!info) return false
+		return opts.absolute ? info.url.href : info.url.pathname + info.url.search + info.url.hash
 	}
 
 	#link_from_event(e, check_button = false) {
@@ -316,20 +480,21 @@ export default class Navgo {
 			!a.target &&
 			!a.download &&
 			a.host === location.host &&
-			this.#base_rgx.test(a.pathname)
+			this.#resolve_url_and_path(href, { literal: true })
 			? { a, href }
 			: null
 	}
 
 	#update_active_links() {
 		if (!this.#opts.aria_current) return
-		const cur = this.format(this.#current.url?.pathname)
+		const cur = this.#current.url && normalize_path(this.#current.url.pathname)
 		if (!cur) return
 		for (const a of document.querySelectorAll('a[href]')) {
 			const href = a.getAttribute('href')
 			if (href[0] === '#') continue
-			const link_path = href && this.#resolve_url_and_path(href)?.path
-			if (link_path === cur) a.setAttribute('aria-current', 'page')
+			const link_url = href && this.#resolve_url_and_path(href, { literal: true })?.url
+			if (link_url && normalize_path(link_url.pathname) === cur)
+				a.setAttribute('aria-current', 'page')
 			else if (a.getAttribute('aria-current') === 'page') a.removeAttribute('aria-current')
 		}
 	}
@@ -376,9 +541,26 @@ export default class Navgo {
 		} catch {}
 	}
 
+	#make_loader_ctx(route, info, params, search_params, controller) {
+		const { url, internal_url = url, path = internal_url?.pathname || '', context } = info || {}
+		return {
+			route_entry: route,
+			url,
+			internal_url,
+			path,
+			context,
+			params,
+			search_params,
+			signal: controller.signal,
+			fetch: (input, init) => fetch(input, { ...init, signal: controller.signal }),
+			invalidate: x => this.invalidate(x),
+		}
+	}
+
 	/* Resolve search schema + options for the current match. */
-	#resolve_search(matches, route, url, params) {
-		const ctx = { route_entry: route, url, params }
+	#resolve_search(matches, route, info, params) {
+		const { url, internal_url = url, path = internal_url?.pathname || '', context } = info || {}
+		const ctx = { route_entry: route, url, internal_url, path, context, params }
 		let schema = null
 		let opts = merge_search_opts(this.#opts.search || {})
 
@@ -406,10 +588,13 @@ export default class Navgo {
 	#set_search_store(values) {
 		const next = values || {}
 		this.#search_syncing = true
-		this.search_params.set(next)
-		this.#search_syncing = false
-		this.#current.search_params = next
-		if (this.#current.url) this.route.set(this.#current)
+		try {
+			this.#current.search_params = next
+			if (this.#current.url) this.route.set(this.#current)
+			this.search_params.set(next)
+		} finally {
+			this.#search_syncing = false
+		}
 	}
 
 	/* Apply resolved search config to current route. */
@@ -512,11 +697,14 @@ export default class Navgo {
 		} catch {}
 		const out = {}
 		const sources = {}
+		const preloads = new Set()
 		const defaults = this.#opts.load_plan_defaults || {}
 		await Promise.all(
 			Object.entries(plan || {}).map(async ([as, raw]) => {
 				const spec = typeof raw === 'string' ? { request: raw } : raw || {}
 				const req = this.#to_get_request(spec.request, spec.init)
+				const url = new URL(req.url)
+				if (url.origin === location.origin) preloads.add(url.pathname + url.search)
 				const parse = spec.parse || defaults.parse || 'json'
 				const cache_hints = { ...(defaults.cache || {}), ...(spec.cache || {}) }
 				const strategy = cache_hints.strategy || 'swr'
@@ -579,7 +767,10 @@ export default class Navgo {
 				sources[as] = source
 			}),
 		)
-		return { ...out, __meta: { source: sources, at: Date.now() } }
+		return {
+			...out,
+			__meta: { source: sources, at: Date.now(), preloads: [...preloads] },
+		}
 	}
 
 	#emit_revalidate(id, as, value) {
@@ -596,6 +787,7 @@ export default class Navgo {
 		try {
 			data[as] = value
 			if (data.__meta?.source) data.__meta.source[as] = 'revalidated'
+			r.nav.status = this.#nav_status(r.nav.to)
 			r.updated = true
 			this.route.set(this.#current)
 			for (const fn of r.cbs || [])
@@ -605,38 +797,9 @@ export default class Navgo {
 		} catch {}
 	}
 
-	async #run_loader(route, url, params, search_params, controller, nav_id) {
-		const loader = this.#get_hooks(route)?.loader
+	async #run_loader_fn(loader, route, info, params, search_params, controller, nav_id) {
 		if (!loader) return undefined
-		const ctx = {
-			route_entry: route,
-			url,
-			params,
-			search_params,
-			signal: controller.signal,
-			fetch: (i, init) => fetch(i, { ...init, signal: controller.signal }),
-			invalidate: x => this.invalidate(x),
-		}
-		const ret = loader(ctx)
-		if (isPromise(ret)) return ret
-		if (ret && typeof ret === 'object' && !Array.isArray(ret))
-			return this.#run_plan(ret, controller, nav_id)
-		return ret
-	}
-
-	async #run_group_loader(group, route, url, params, search_params, controller, nav_id) {
-		const loader = group?.loader
-		if (!loader) return undefined
-		const ctx = {
-			route_entry: route,
-			url,
-			params,
-			search_params,
-			signal: controller.signal,
-			fetch: (i, init) => fetch(i, { ...init, signal: controller.signal }),
-			invalidate: x => this.invalidate(x),
-		}
-		const ret = loader(ctx)
+		const ret = loader(this.#make_loader_ctx(route, info, params, search_params, controller))
 		if (isPromise(ret)) return ret
 		if (ret && typeof ret === 'object' && !Array.isArray(ret))
 			return this.#run_plan(ret, controller, nav_id)
@@ -663,6 +826,17 @@ export default class Navgo {
 		return out
 	}
 
+	#nav_status(target) {
+		const err = target?.data?.__error
+		return typeof err?.status === 'number'
+			? err.status
+			: err
+				? 500
+				: target?.route === null
+					? 404
+					: 200
+	}
+
 	#build_matches(route, stack) {
 		const out = []
 		for (const g of stack || []) {
@@ -675,9 +849,10 @@ export default class Navgo {
 		return out
 	}
 
-	async #load_hit(hit, url, controller, nav_id) {
+	async #load_hit(hit, info, controller, nav_id) {
 		const matches = hit.matches || this.#build_matches(hit.route, hit.stack)
-		const { schema, opts } = this.#resolve_search(matches, hit.route, url, hit.params)
+		const { url } = info || {}
+		const { schema, opts } = this.#resolve_search(matches, hit.route, info, hit.params)
 
 		const defaults = schema ? v.getDefaults(schema) || {} : {}
 		const search_params = schema
@@ -685,19 +860,19 @@ export default class Navgo {
 			: {}
 
 		const ps = matches.map(m => {
-			const p =
-				m.type === 'route'
-					? this.#run_loader(m.route, url, hit.params, search_params, controller, nav_id)
-					: this.#run_group_loader(
-							m.__entry,
-							hit.route,
-							url,
-							hit.params,
-							search_params,
-							controller,
-							nav_id,
-						)
-			return Promise.resolve(p).catch(e => ({ __error: e }))
+			const entry = m.type === 'route' ? this.#get_hooks(m.route) : m.__entry
+			const route = m.type === 'route' ? m.route : hit.route
+			return Promise.resolve(
+				this.#run_loader_fn(
+					entry?.loader,
+					route,
+					info,
+					hit.params,
+					search_params,
+					controller,
+					nav_id,
+				),
+			).catch(e => ({ __error: e }))
 		})
 		const datas = await Promise.all(ps)
 		for (let i = 0; i < matches.length; i++) matches[i].data = datas[i]
@@ -713,22 +888,22 @@ export default class Navgo {
 	 * @returns {Navigation}
 	 */
 	#make_nav({ type, from = undefined, to = undefined, will_unload = false, event = undefined }) {
-		const from_obj =
-			from !== undefined
-				? from
-				: this.#current.url
-					? {
-							url: this.#current.url,
-							params: this.#current.params || {},
-							route: this.#current.route,
-							matches: this.#current.matches || [],
-							layouts: this.#current.layouts || Object.create(null),
-						}
-					: null
+		const from_obj = from !== undefined ? from : this.#target(this.#current)
+		const ssr = to?.route && this.#get_hooks(to.route)?.ssr
 		return {
 			type, // 'link' | 'goto' | 'popstate' | 'leave'
 			from: from_obj,
 			to,
+			status: 200,
+			ssr:
+				ssr && typeof ssr === 'object'
+					? {
+							serve_shell: ssr.serve_shell === true,
+							refresh_every: Number.isFinite(ssr.refresh_every)
+								? Math.max(0, Math.floor(ssr.refresh_every))
+								: 0,
+						}
+					: undefined,
 			will_unload,
 			cancelled: false,
 			event,
@@ -762,7 +937,7 @@ export default class Navgo {
 		}
 
 		try {
-			const info = this.#resolve_url_and_path(url_raw)
+			const info = this.#resolve_url_and_path(url_raw, opts)
 			if (!info) return void ℹ('[🧭 goto]', 'invalid url', { url: url_raw })
 			this.is_navigating.set(true)
 
@@ -780,7 +955,7 @@ export default class Navgo {
 
 			let nav = this.#make_nav({
 				type: nav_type,
-				to: { url, params: {}, route: null, matches: [], layouts: Object.create(null) },
+				to: this.#target(info),
 				event: ev_param,
 			})
 			ℹ('[🧭 goto]', 'start', {
@@ -808,16 +983,19 @@ export default class Navgo {
 				ℹ('[🧭 match]', 'error', { err: e })
 			}
 			if (nav_id !== this.#nav_active) return
-			nav.to = hit
-				? {
-						url,
-						params: hit.params || {},
-						route: hit.route || null,
-						matches: hit.matches || [],
-						layouts: hit.layouts || this.#build_layouts(hit.matches || []),
-					}
-				: { url, params: {}, route: null, matches: [], layouts: Object.create(null) }
+			nav.to = this.#target(
+				hit
+					? {
+							...info,
+							params: hit.params || {},
+							route: hit.route || null,
+							matches: hit.matches || [],
+							layouts: hit.layouts || this.#build_layouts(hit.matches || []),
+						}
+					: info,
+			)
 			if (match_error) nav.to.data = { __error: match_error }
+			nav.status = this.#nav_status(nav.to)
 
 			// before_navigate (skip initial)
 			if (nav.from) {
@@ -844,7 +1022,7 @@ export default class Navgo {
 				const pre = this.#preloads.get(load_key)
 				bundle =
 					pre?.data ??
-					(await (pre?.promise || this.#load_hit(hit, url, controller, nav_id)).catch(
+					(await (pre?.promise || this.#load_hit(hit, info, controller, nav_id)).catch(
 						e => ({
 							matches: [],
 							data: { __error: e },
@@ -881,20 +1059,23 @@ export default class Navgo {
 
 			const prev = this.#current
 			const matches = hit && !match_error ? bundle?.matches || [] : []
+			const layouts =
+				hit && !match_error
+					? bundle?.layouts || this.#build_layouts(matches)
+					: Object.create(null)
 			const data = match_error
 				? { __error: match_error }
 				: hit
 					? bundle?.data
 					: { __error: { status: 404 } }
 			this.#current = {
-				url,
-				route: match_error ? null : hit?.route || null,
-				params: match_error ? {} : hit?.params || {},
-				matches,
-				layouts:
-					hit && !match_error
-						? bundle?.layouts || this.#build_layouts(matches)
-						: Object.create(null),
+				...this.#target({
+					...info,
+					route: match_error ? null : hit?.route || null,
+					params: match_error ? {} : hit?.params || {},
+					matches,
+					layouts,
+				}),
 				search_params: {},
 			}
 
@@ -903,25 +1084,11 @@ export default class Navgo {
 			// Build a completion nav using the previous route as `from`
 			nav = this.#make_nav({
 				type: nav_type,
-				from: prev?.url
-					? {
-							url: prev.url,
-							params: prev.params || {},
-							route: prev.route,
-							matches: prev.matches || [],
-							layouts: prev.layouts || Object.create(null),
-						}
-					: null,
-				to: {
-					url,
-					params: match_error ? {} : hit?.params || {},
-					route: match_error ? null : hit?.route || null,
-					matches,
-					layouts: this.#current.layouts || Object.create(null),
-					data,
-				},
+				from: this.#target(prev),
+				to: this.#target(this.#current, { data }),
 				event: ev_param,
 			})
+			nav.status = this.#nav_status(nav.to)
 			this.nav = nav
 
 			// Wire up revalidation tracking early (revalidate fetches can resolve before after_navigate runs).
@@ -938,6 +1105,7 @@ export default class Navgo {
 						}
 					}
 					reval.pending.clear()
+					nav.status = this.#nav_status(nav.to)
 				}
 			}
 
@@ -1004,7 +1172,7 @@ export default class Navgo {
 			)
 		} catch {}
 		const idx = prev_idx + (replace ? 0 : 1)
-		const from = this.#current.url?.pathname || location.pathname
+		const from = normalize_path(this.#current.url?.pathname || location.pathname)
 		const st = { ...state, __navgo: { shallow: true, idx, from } }
 		history[(replace ? 'replace' : 'push') + 'State'](st, '', u.href)
 		ℹ('[🧭 history]', replace ? 'replace_state(shallow)' : 'push_state(shallow)', {
@@ -1020,9 +1188,12 @@ export default class Navgo {
 		m.set('window', { x: scrollX || 0, y: scrollY || 0 })
 		this.#areas_pos.set(idx, m)
 		// update current URL snapshot and notify
-		this.#current.url = u
-		this.#sync_search_from_url(u)
-		this.route.set(this.#current)
+		const next_current = this.#update_current_info(
+			this.#resolve_url_and_path(u.href, { literal: true }),
+			u,
+		)
+		this.#sync_search_from_url(next_current.url)
+		this.route.set(next_current)
 		this.#update_active_links()
 	}
 
@@ -1081,14 +1252,12 @@ export default class Navgo {
 	 * Dedupes concurrent preloads for the same path.
 	 */
 	/** @param {string} url_raw @returns {Promise<unknown|void>} */
-	async preload(url_raw) {
+	async preload(url_raw, opts = {}) {
 		try {
-			const { path, url, load_key } = this.#resolve_url_and_path(url_raw) || {}
+			const info = this.#resolve_url_and_path(url_raw, opts)
+			const { path, load_key } = info || {}
 			if (!path) return void ℹ('[🧭 preload]', 'invalid url', { url: url_raw })
-			if (
-				this.format(this.#current.url?.pathname) + (this.#current.url?.search || '') ===
-				load_key
-			)
+			if (this.#current.url && this.#public_key(this.#current.url) === load_key)
 				return void ℹ('[🧭 preload]', 'skip current path', { path })
 			const hit = await this.match(path).catch(() => null)
 			if (!hit) return void ℹ('[🧭 preload]', 'no route', { path })
@@ -1101,7 +1270,7 @@ export default class Navgo {
 
 			const entry = {}
 			const controller = new AbortController()
-			entry.promise = this.#load_hit(hit, url, controller, 0).then(
+			entry.promise = this.#load_hit(hit, info, controller, 0).then(
 				bundle => {
 					entry.data = bundle
 					delete entry.promise
@@ -1209,6 +1378,9 @@ export default class Navgo {
 		this.#base_rgx =
 			this.#base == '/' ? /^\/+/ : new RegExp('^\\' + this.#base + '(?=\\/|$)\\/?', 'i')
 
+		const initial = this.#resolve_public_url(location.href)
+		if (initial) this.route.set({ ...this.#target(initial), search_params: {} })
+
 		const group_ids = new Map()
 
 		function compile_routes(entries, stack = []) {

package/llms.txt

@@ -4,15 +4,19 @@
 - route hooks (`loader`, `param_rules`, `search_schema`, `search_options`, `before_route_leave`) live in the route file’s `<script module>`
 - navigation: match -> leave-guard (`before_route_leave`, can `nav.cancel()`) -> loaders -> update stores -> `after_navigate(nav)`
 - `goto()` and `preload()` are safe to call without `await` from events (no unhandled rejections); errors surface via `nav.to.data.__error` (or preload bundle `data.__error`)
+- `nav.status` is the official HTTP-like status for the completed route; unmatched routes are `404`, and `data.__error.status` wins when present
+- `rewrite.input` maps a public browser URL into the canonical internal path before matching; `rewrite.output` maps an internal target back into a public URL for history/links
+- `router.href('/internal')` builds a public in-app URL from a canonical internal path; pass `{ literal: true }` only when the input is already public
 - `router.init()` attaches the router instance to `window.navgo` by default
 - stores:
-  - `window.navgo.route`: `{ url, route, params, matches, layouts, search_params }`
+  - `window.navgo.route`: `{ url, internal_url, path, context, route, params, matches, layouts, search_params }`
   - `window.navgo.is_navigating`: boolean
 
 ## Setup (App Wiring)
 
 - `const router = new Navgo(routes, { after_navigate })`; `await router.init()` once at startup
-- `after_navigate(nav)` sets app props: `route_data = nav.to?.data ?? null`, `is_404 = nav.to?.data?.__error?.status === 404`, `Component = leaf route module default`
+- `after_navigate(nav)` sets app props: `route_data = nav.to?.data ?? null`, `is_404 = nav.status === 404`, `Component = leaf route module default`
+- `nav.ssr` is resolved from the matched leaf route's `ssr` export before `after_navigate(nav)` runs
 - render `Component` keyed by `$route.url.pathname`, pass `data={route_data}`
 
 ## Patterns / Usage
@@ -22,12 +26,13 @@
   - update via `window.navgo.search_params.update(o => ({ ...o, q: 'x', page: 1 }))` (shallow URL update; loaders are not re-run)
   - common pattern: loader uses `search_params` for initial data, then a `$effect` refetches when `$search_params` changes
 - Loaders:
+  - loader/search hook ctx includes both public `url` and canonical `internal_url`, plus canonical `path` and arbitrary rewrite `context`
   - returning a non-Promise object means a LoadPlan (cached fetch plan), not plain data; return plain object data via `async loader()`
   - layout/group loaders run outer → inner and their results are on `nav.to.matches[*].data` (leaf convenience stays on `nav.to.data`)
   - SWR revalidation can update `nav.to.data` after navigation; subscribe via `after_navigate(nav, on_revalidate)`
   - Avoid these common mistakes:
     - Re-fetching the same data in the component `<script>` that the loader already fetched (double network + out-of-sync state). Prefer using the `data` prop.
-    - Overcomplicating the loader: keep it as a LoadPlan (just URLs/specs). Do client-side orchestration in the component only if it truly depends on interactive state.
+    - Overcomplicating the loader: do not keep an `async loader()` just to do `filter`/`map`/`sort`-style normalization. Usually keep the loader as a LoadPlan (just URLs/specs) and normalize in the component. Use `async loader()` when later fetches depend on earlier results.
     - Duplicating imports across `<script>` and `<script module>`: in Svelte they share imports; duplicating can cause compile errors. Put imports in one place.
 - Shallow history:
   - `push_state`/`replace_state` updates URL/state without re-running loaders
@@ -40,6 +45,7 @@
 - `goto` usage:
   - prefer plain `<a href="/path">`
   - use `window.navgo.goto('/path')` for buttons/menus/command palette
+  - with rewrites, keep route patterns canonical (example: `'/about'`) and switch public variants through `context`/`href()` instead of duplicating route entries
 
 ## Recipes / Common Scenarios
 
@@ -50,9 +56,12 @@
 - SWR revalidate refresh:
   - `after_navigate(nav, on_revalidate) { render(nav.to?.data); on_revalidate?.(() => render(nav.to?.data)) }`
 - Handle 404 / loader errors:
-  - `const err = nav.to?.data?.__error; if (err?.status === 404) show_404 = true`
+  - `if (nav.status === 404) show_404 = true`
 - Shared layout data:
   - use `nav.to.layouts?.id?.data` or `$route.layouts?.id?.data` for direct access to matched group data
   - `nav.to.matches` remains the ordered outer → inner structure; layouts are `m.type === 'layout'`, route leaf is `m.type === 'route'`
+- Localized/public URL variants:
+  - locale prefixes, vanity slugs, and similar browser-only transforms belong in `rewrite`, not in duplicated route patterns
+  - `nav.to.url` is the public browser URL; `nav.to.internal_url` / `nav.to.path` are the canonical values your routes and loaders should reason about
 - Stable scroll panes:
   - set `id="pane"` or `data-scroll-id="pane"` on scroll containers to get popstate restoration

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "navgo",
-	"version": "6.0.5",
+	"version": "6.0.8",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/mustafa0x/navgo.git"

package/readme.md

@@ -37,7 +37,7 @@ const props = $state({
 })
 
 function after_navigate(nav, on_revalidate) {
-  props.is_404 = nav.to?.data?.__error?.status === 404
+  props.is_404 = nav.status === 404
   props.route_data = nav.to?.data ?? null
   props.Component = nav.to?.route?.[1]?.default ?? null
   on_revalidate?.(() => {
@@ -145,11 +145,14 @@ Notes:
 
 - `base`: `string` (default `'/'`)
   - App base pathname. With or without leading/trailing slashes is accepted.
+- `rewrite`: `{ input?: (ctx) => string | URL | { url?: string | URL; context?: unknown } | void; output?: (ctx) => string | URL | { url?: string | URL; context?: unknown } | void }`
+  - Optional bidirectional URL rewrite hooks. `input` maps a public URL into Navgo's canonical internal path before matching, while `output` maps an internal target back into a public URL for history, links, and preloading. Useful for locale prefixes like `/en/...` without duplicating routes.
 - `before_navigate`: `(nav: Navigation) => void`
   - App-level hook called once per navigation attempt after the per-route guard and before loader/URL update. May call `nav.cancel()` synchronously to prevent navigation.
 - `after_navigate`: `(nav: Navigation, on_revalidate?: (cb: () => void) => void) => void | Promise<void>`
-  - App-level hook called after routing completes (URL updated, data loaded). `nav.to.data` holds any loader data.
+  - App-level hook called after routing completes (URL updated, data loaded). `nav.to.data` holds any loader data, and `nav.status` is the HTTP-like status for the completed route.
   - If the active route uses SWR and a stale entry is revalidated in the background, register a callback via `on_revalidate(cb)` to refresh UI.
+  - `nav.ssr` is resolved from the matched leaf route's `ssr` export before this hook runs.
 - `tick`: `() => void | Promise<void>`
   - Awaited after `after_navigate` and before scroll handling; useful for frameworks to flush DOM so anchor/top scrolling lands correctly.
 - `scroll_to_top`: `boolean` (default `true`)
@@ -173,7 +176,7 @@ Important: Navgo only processes routes that match your `base` path.
 
 ### Instance stores
 
-- `router.route` -- `Writable<{ url: URL; route: RouteTuple|null; params: Params; matches: Match[]; layouts: Record<string, Match>; search_params: SearchParams }>`
+- `router.route` -- `Writable<{ url: URL; internal_url: URL; path: string; context?: unknown; route: RouteTuple|null; params: Params; matches: Match[]; layouts: Record<string, Match>; search_params: SearchParams }>`
   - Readonly property that holds the current snapshot.
   - Subscribe to react to changes; Navgo updates it on every URL change.
 - `router.is_navigating` -- `Writable<boolean>`
@@ -188,6 +191,7 @@ Example:
 
 ```svelte
 Current path: {$route.path}
+Current public URL: {$route.url.pathname}
 <div class="request-indicator" class:active={$is_navigating}></div>
 
 <script>
@@ -224,9 +228,9 @@ import { v } from 'navgo'
 export const search_schema = v.object({
   q: v.optional(v.fallback(v.string(), ''), ''),
   page: v.optional(v.fallback(v.number(), 1), 1),
-	// arrays are supported
-	tag: v.optional(v.fallback(v.array(v.string()), []), []),
-	cat: v.optional(v.fallback(v.array(v.string()), []), []),
+  // arrays are supported
+  tag: v.optional(v.fallback(v.array(v.string()), []), []),
+  cat: v.optional(v.fallback(v.array(v.string()), []), []),
 })
 
 export const search_options = {
@@ -234,8 +238,8 @@ export const search_options = {
   push_history: true,
   show_defaults: false,
   sort: true,
-	// arrays default to 'repeat' (?tag=a&tag=b). When using a map, `default` is the fallback for keys you don't list.
-	array_style: { default: 'repeat', cat: 'csv' },
+  // arrays default to 'repeat' (?tag=a&tag=b). When using a map, `default` is the fallback for keys you don't list.
+  array_style: { default: 'repeat', cat: 'csv' },
 }
 ```
 
@@ -266,22 +270,25 @@ Load plans let you define one or more fetches that Navgo can cache via the Cache
 
 ```js
 // sync => treated as a LoadPlan
-function loader({params}) {
+function loader({ params }) {
   return {
     product: `https://dummyjson.com/products/${params.id}`,
     reviews: {
       request: `https://example.com/reviews/${params.id}`,
-      cache: {strategy: 'cache-first', ttl: 60_000, tags: ['reviews']},
+      cache: { strategy: 'cache-first', ttl: 60_000, tags: ['reviews'] },
     },
   }
 }
 
 // async => treated as plain data
 async function loader(ctx) {
-  return {session: await ctx.fetch('/api/session').then(r => r.json())}
+  return { session: await ctx.fetch('/api/session').then(r => r.json()) }
 }
 ```
 
+`ctx.fetch(...)` is just `fetch(...)` with the current navigation's abort `signal` already attached.
+Use plain `fetch` if you do not need navigation-scoped cancellation.
+
 Global defaults for LoadPlans can be set in `options`:
 
 ```js
@@ -295,6 +302,10 @@ const router = new Navgo(routes, {
 
 See `examples.md` for more setups.
 
+Executed LoadPlans also expose the fetched same-origin request URLs on `data.__meta.preloads` as
+relative `pathname + search` strings. This is useful for SSR services that want to turn LoadPlan
+requests into `Link: rel=preload` headers. Async loaders that return plain data do not produce
+`__meta.preloads`.
 
 - param_rules?: `Record<string, ParamRule>`
   - Each rule is either a Valibot schema or `{ schema, coercer }`.
@@ -304,6 +315,8 @@ See `examples.md` for more setups.
   - If you return a **non-Promise object**, it is treated as a `LoadPlan` and executed (each entry can be cached).
   - If you return a **Promise**, it is awaited and the resolved value becomes `nav.to.data`.
   - To return a plain object as data, make the loader `async`.
+- ssr?: `{ serve_shell?: boolean; refresh_every?: number }`
+  - Optional SSR metadata for the leaf route. Navgo exposes it on completed navigations as `nav.ssr`.
 - validate?(params): `boolean | Promise<boolean>`
   - Predicate called during matching. If it returns or resolves to `false`, the route is skipped.
 - before_route_leave?(nav): `(nav: Navigation) => void`
@@ -362,7 +375,7 @@ const routes = [
       param_rules: {
         account_id: v.pipe(v.string(), v.toNumber(), v.minValue(1)),
       },
-      loader: ({params}) => fetch(`/api/account/${params.account_id}`).then(r => r.json()),
+      loader: ({ params }) => fetch(`/api/account/${params.account_id}`).then(r => r.json()),
       before_route_leave(nav) {
         if (nav.type === 'link' || nav.type === 'goto') {
           if (!confirm('Leave account settings?')) nav.cancel()
@@ -383,9 +396,9 @@ router.init()
 
 Returns: `String` or `false`
 
-Formats and returns a pathname relative to the [`base`](#base) path.
+Parses a public URL relative to the configured [`base`](#base) path and optional `rewrite.input`, then returns the canonical internal pathname.
 
-If the `uri` **does not** begin with the `base`, then `false` will be returned instead.<br>
+If the `uri` **does not** belong to the app's `base`, then `false` will be returned instead.<br>
 Otherwise, the return value will always lead with a slash (`/`).
 
 > **Note:** This is called automatically within the [`init()`](#init) method.
@@ -398,6 +411,22 @@ The path to format.
 
 > **Note:** Much like [`base`](#base), paths with or without leading and trailing slashes are handled identically.
 
+### href(uri, options?)
+
+Returns: `String` or `false`
+
+Builds a public in-app URL from an internal target. This is the forward counterpart to [`format()`](#formaturi) and is especially useful when combined with `rewrite.output` (for example, locale prefixes).
+
+#### options
+
+Type: `Object`
+
+- absolute: `Boolean` (default `false`)
+- literal: `Boolean` (default `false`)
+- context: `Any`
+
+When `literal` is `true`, the `uri` is treated as an already-public URL and is only validated/normalized. Otherwise Navgo treats ambiguous inputs like `/about` and same-origin absolute `URL` values as canonical internal targets and applies `base` + `rewrite.output` when building the final public URL.
+
 ### goto(uri, options?)
 
 Returns: `Promise<void>`
@@ -406,16 +435,19 @@ Runs any matching route `loader` before updating the URL and then updates histor
 
 #### uri
 
-Type: `String`
+Type: `String | URL`
 
-The desired path to navigate. If it begins with `/` and does not match the configured [`base`](#base), it will be prefixed automatically.
+The desired path to navigate. When `literal` is `false`, ambiguous paths like `/about` and same-origin absolute `URL` values are treated as canonical internal targets and are passed through `base` + `rewrite.output`.
 
 #### options
 
 Type: `Object`
 
 - replace: `Boolean` (default `false`)
-- When `true`, uses `history.replaceState`; otherwise `history.pushState`.
+- literal: `Boolean` (default `false`)
+- context: `Any`
+- When `true`, `replace` uses `history.replaceState`; otherwise `history.pushState`.
+- When `literal` is `true`, the `uri` is interpreted as the already-public browser URL. Otherwise ambiguous inputs like `/about` and same-origin absolute `URL` values are treated as canonical internal targets and pass through `rewrite.output`.
 
 ### init()
 
@@ -464,11 +496,11 @@ Or with a custom id:
 <div data-scroll-id="pane">...</div>
 ```
 
-### preload(uri)
+### preload(uri, options?)
 
 Returns: `Promise<unknown | void>`
 
-Preload a route's `loader` data for a given `uri` without navigating. Concurrent calls for the same path are deduped.
+Preload a route's `loader` data for a given `uri` without navigating. Concurrent calls for the same public URL are deduped. Accepts the same `literal` / `context` options as [`goto()`](#gotouri-options).
 Note: Resolves to `undefined` when the matched route has no `loader`.
 
 ### push_state(url?, state?)
@@ -566,12 +598,13 @@ scroll flow
 
 ### Method-by-Method Semantics
 
-- `format(uri)` -- normalizes a path relative to `base`. Returns `false` when `uri` is outside of `base`.
+- `format(uri)` -- parses a public URL relative to `base` and `rewrite.input`, returning the canonical internal path. Returns `false` when `uri` is outside of `base`.
 - `match(uri)` -- returns a Promise of `{ route, params, matches, layouts } | null` using string/RegExp patterns and `param_rules` (Valibot schemas). Awaits an async `validate(params)` if provided.
-- `goto(uri, { replace? })` -- fires route-level `before_route_leave('goto')`, calls global `before_navigate`, saves scroll, runs loader, pushes/replaces, and completes via `after_navigate`.
+- `href(uri, options?)` -- builds a public in-app URL from a canonical internal target (or validates a literal public URL when `literal: true`).
+- `goto(uri, { replace?, literal?, context? })` -- fires route-level `before_route_leave('goto')`, calls global `before_navigate`, saves scroll, runs loader, pushes/replaces, and completes via `after_navigate`.
 - `init()` -- wires global listeners (`popstate`, `pushstate`, `replacestate`, click) and optional hover/tap preloading; immediately processes the current location.
 - `destroy()` -- removes listeners added by `init()`.
-- `preload(uri)` -- pre-executes a route's `loader` for a path and caches the result; concurrent calls are deduped.
+- `preload(uri, { literal?, context? })` -- pre-executes a route's `loader` for a path and caches the result; concurrent calls are deduped by public URL.
 - `push_state(url?, state?)` -- shallow push that updates the URL and `history.state` without route processing.
 - `replace_state(url?, state?)` -- shallow replace that updates the URL and `history.state` without route processing.