@octane-xplat/ui 0.9.0 → 0.11.0

package/src/route-table.ts

@@ -1,5 +1,5 @@
 /** Shared route-dir manifest — the file-router half of the nav contract
- *  (docs/navigation-notes.md). Apps glob their route dir per platform and
+ *  (docs/notes/navigation-notes.md). Apps glob their route dir per platform and
  *  pass the module map here; the suffix seam applies to directories the
  *  same way it does to imports:
  *
@@ -20,6 +20,8 @@
  *  Conventions (route dir = `dir`, default 'app'):
  *    app/detail.tsrx        → route 'detail'
  *    app/demo/[id].tsrx     → route 'demo/:id'  ([param] → :param)
+ *    app/demo/[[ref]].tsrx  → 'demo/:ref?'    ([[p]] = optional param)
+ *    app/docs/[...r].tsrx   → 'docs/*r'       ([...p] = terminal catch-all)
  *    app/foo/index.tsrx     → 'foo'           (index = the dir's own route)
  *    app/settings.web.tsrx  → 'settings' on web only — `prefer` decides
  *    app/_layout.tsrx       → layouts['']     — a shell, not a route
@@ -43,6 +45,56 @@ import type {
 const EXT = /\.(tsrx|tsx|ts|mts|cts|js|mjs|cjs|jsx)$/
 const SUFFIX = /\.(web|mobile|ios|android|macos|windows|linux)$/
 const PARAM = /^\[(.+)\]$/
+
+/** One route-dir/spec path segment → normalized pattern segment:
+ *  `[x]`→`:x` · `[[x]]`/`[x?]`→`:x?` (optional param) · `[...x]`→`*x`
+ *  (terminal catch-all). Spec paths may write the normalized forms
+ *  directly (`:x`, `:x?`, `*`, `*x`); a bare `*` captures into
+ *  `params['*']`, a named `*x`/`[...x]` into `params.x`. */
+function normSegment(s: string): string {
+	const b = PARAM.exec(s)
+	if (!b) {
+		return s
+	}
+
+	const inner = b[1]
+	if (inner.startsWith('[') && inner.endsWith(']')) {
+		const core = inner.slice(1, -1)
+		return core.startsWith('...') ? '*' + core.slice(3) : ':' + core + '?'
+	}
+
+	return inner.startsWith('...') ? '*' + inner.slice(3) : ':' + inner
+}
+
+/** Normalized pattern segment → param name: ':x'/':x?' → 'x',
+ *  '*'/'*x' → '*'/'x', static segments → undefined. */
+function segmentParam(s: string): string | undefined {
+	if (s.startsWith(':')) {
+		return s.endsWith('?') ? s.slice(1, -1) : s.slice(1)
+	}
+
+	if (s.startsWith('*')) {
+		return s.slice(1) || '*'
+	}
+
+	return undefined
+}
+
+function segmentParams(segments: readonly string[]): string[] {
+	return segments.flatMap((s) => segmentParam(s) ?? [])
+}
+
+/** A catch-all only matches at the end of a pattern — warn that a
+ *  mid-path '*' is a literal segment, not a remainder capture. */
+function warnOnStraySplat(segments: readonly string[], file: string): void {
+	const at = segments.findIndex((s) => s.startsWith('*'))
+	if (at !== -1 && at !== segments.length - 1) {
+		console.warn(
+			`[octane-xplat] route '${segments.join('/')}' (${file}) has a catch-all segment mid-path — '*' only captures at the end of a pattern and is a literal here`,
+		)
+	}
+}
+
 /** Build-time loader modules — `docs.loader.ts` pairs with route `docs`
  *  for `dataMode: 'baked'`. Never a route itself, never in a runtime glob. */
 const LOADER_FILE = /\.loader\.(ts|mts|cts|js|mjs|cjs|jsx)$/
@@ -91,7 +143,9 @@ function pick(mod: any, file: string): any {
 	}
 
 	const fns = Object.keys(mod ?? {}).filter(
-		(k) => typeof mod[k] === 'function' && !['loader', 'beforeLoad', 'head'].includes(k),
+		(k) =>
+			typeof mod[k] === 'function' &&
+			!['loader', 'beforeLoad', 'head', 'ErrorBoundary'].includes(k),
 	)
 
 	if (fns.length === 1) {
@@ -175,20 +229,18 @@ export function deriveRouteManifest(
 			segs.pop()
 		}
 
-		const segments = segs.map((s) => {
-			const p = PARAM.exec(s)
-			return p ? ':' + p[1] : s
-		})
-
+		const segments = segs.map(normSegment)
 		const name = segments.join('/') || 'index'
 		const meta: RouteMeta = {
 			name,
 			segments,
-			params: segments.filter((s) => s.startsWith(':')).map((s) => s.slice(1)),
+			params: segmentParams(segments),
 			file: key,
 			presentation,
 		}
 
+		warnOnStraySplat(segments, key)
+
 		const dataMode = files[key]?.dataMode
 		if (dataMode === 'baked' || dataMode === 'live') {
 			meta.dataMode = dataMode
@@ -211,6 +263,11 @@ export function deriveRouteManifest(
 			meta.beforeLoad = beforeLoad
 		}
 
+		const errorBoundary = files[key]?.ErrorBoundary
+		if (typeof errorBoundary === 'function') {
+			meta.errorBoundary = errorBoundary
+		}
+
 		if (
 			files[key]?.head &&
 			(typeof files[key].head === 'object' || typeof files[key].head === 'function')
@@ -254,27 +311,27 @@ export function deriveRouteManifest(
 	return manifest
 }
 
-/** Match-order comparator: static segments (2) outrank params (1), ties
- *  break alphabetically so ordering is total and stable across merges. */
+/** Match-order comparator: static (3) outranks a required param (2),
+ *  which outranks an optional param (1), which outranks a catch-all (0).
+ *  Ties break alphabetically so ordering is total and stable across
+ *  merges. */
 function bySpecificity(a: RouteMeta, b: RouteMeta): number {
+	const weight = (s: string) =>
+		s.startsWith('*') ? 0 : s.startsWith(':') ? (s.endsWith('?') ? 1 : 2) : 3
+
 	return (
-		b.segments.reduce((n, s) => n + (s.startsWith(':') ? 1 : 2), 0) -
-			a.segments.reduce((n, s) => n + (s.startsWith(':') ? 1 : 2), 0) ||
+		b.segments.reduce((n, s) => n + weight(s), 0) - a.segments.reduce((n, s) => n + weight(s), 0) ||
 		a.name.localeCompare(b.name)
 	)
 }
 
 /** Normalize a programmatic `path` into manifest segments using the
  *  route-dir vocabulary: `'docs/[slug]'` and `'docs/:slug'` are the same
- *  pattern, a trailing `index` drops, `''`/`'index'` name the root route. */
+ *  pattern, `':slug?'`/`'[slug?]'`/`'[[slug]]'` mark an optional segment,
+ *  a terminal `'*'`/`'[...rest]'` is a catch-all, a trailing `index`
+ *  drops, `''`/`'index'` name the root route. */
 function specSegments(path: string): string[] {
-	const segs = path
-		.split('/')
-		.filter(Boolean)
-		.map((s) => {
-			const p = PARAM.exec(s)
-			return p ? ':' + p[1] : s
-		})
+	const segs = path.split('/').filter(Boolean).map(normSegment)
 
 	if (segs[segs.length - 1] === 'index') {
 		segs.pop()
@@ -324,11 +381,13 @@ export function defineRoutes<const Specs extends readonly RouteSpec[]>(
 		const meta: RouteMeta = {
 			name,
 			segments,
-			params: segments.filter((s) => s.startsWith(':')).map((s) => s.slice(1)),
+			params: segmentParams(segments),
 			file: spec.source ?? `programmatic:${spec.path}`,
 			presentation: spec.presentation,
 		}
 
+		warnOnStraySplat(segments, meta.file)
+
 		if (spec.dataMode) {
 			meta.dataMode = spec.dataMode
 		}
@@ -348,6 +407,10 @@ export function defineRoutes<const Specs extends readonly RouteSpec[]>(
 			meta.beforeLoad = spec.beforeLoad
 		}
 
+		if (spec.errorBoundary) {
+			meta.errorBoundary = spec.errorBoundary
+		}
+
 		if (spec.head) {
 			meta.head = spec.head
 		}
@@ -455,6 +518,7 @@ export function manifestToJson(manifest: RouteManifest): RouteManifestJson {
 				loader: !!meta.loader,
 				guard: !!meta.beforeLoad,
 				head: !!meta.head,
+				errorBoundary: !!meta.errorBoundary,
 			}
 		}),
 	}
@@ -462,55 +526,120 @@ export function manifestToJson(manifest: RouteManifest): RouteManifestJson {
 
 /** Match URL path segments against a manifest — returns the winning meta
  *  plus extracted params, or null. First hit wins (routes are pre-sorted
- *  by specificity). */
+ *  by specificity). A `:param?` segment matches zero or one segment —
+ *  the matcher consumes greedily and backtracks to the absent case so a
+ *  later static can still align; a terminal `*` captures the remaining
+ *  segments `/`-joined into `params['*']` (a named `*rest` into 'rest'). */
 export function matchRoute(
 	routes: readonly RouteMeta[],
 	segs: string[],
 ): { meta: RouteMeta; params: Record<string, unknown> } | null {
 	for (const meta of routes) {
-		if (meta.segments.length !== segs.length) {
-			continue
+		const params = matchSegments(meta.segments, segs)
+		if (params) {
+			return { meta, params }
 		}
+	}
 
-		const params: Record<string, unknown> = {}
-		let ok = true
-		for (let i = 0; i < segs.length; i++) {
-			const p = meta.segments[i]
-			if (p.startsWith(':')) {
-				params[p.slice(1)] = decodeRouteParam(decodeURIComponent(segs[i]))
-			} else if (p !== segs[i]) {
-				ok = false
-				break
+	return null
+}
+
+/** Variable-length pattern match — optional segments try consuming a
+ *  segment first and fall back to absent, so the more specific reading
+ *  wins; a backtracking miss deletes the tentative param before the
+ *  absent retry. */
+function matchSegments(pattern: readonly string[], segs: string[]): Record<string, unknown> | null {
+	const params: Record<string, unknown> = {}
+
+	const walk = (pi: number, si: number): boolean => {
+		if (pi === pattern.length) {
+			return si === segs.length
+		}
+
+		const p = pattern[pi]
+		if (p.startsWith('*')) {
+			// Non-terminal '*' (warned about at manifest build) is a literal.
+			if (pi !== pattern.length - 1) {
+				return p === segs[si] && walk(pi + 1, si + 1)
 			}
+
+			params[segmentParam(p)!] = segs
+				.slice(si)
+				.map((s) => decodeURIComponent(s))
+				.join('/')
+
+			return true
 		}
 
-		if (ok) {
-			return { meta, params }
+		if (p.startsWith(':') && p.endsWith('?')) {
+			const name = p.slice(1, -1)
+			if (si < segs.length) {
+				params[name] = decodeRouteParam(decodeURIComponent(segs[si]))
+				if (walk(pi + 1, si + 1)) {
+					return true
+				}
+
+				delete params[name]
+			}
+
+			return walk(pi + 1, si)
+		}
+
+		if (si >= segs.length) {
+			return false
+		}
+
+		if (p.startsWith(':')) {
+			params[p.slice(1)] = decodeRouteParam(decodeURIComponent(segs[si]))
+			return walk(pi + 1, si + 1)
 		}
+
+		return p === segs[si] && walk(pi + 1, si + 1)
 	}
 
-	return null
+	return walk(0, 0) ? params : null
 }
 
 /** Serialize a Route to a URL path (no origin): manifest routes substitute
- *  `:param` segments from params (leftover params → query string);
+ *  `:param` segments from params (leftover params → query string); a
+ *  `:param?` segment with no value drops out of the path entirely, and a
+ *  terminal `*`/`*rest` splices in its `/`-joined param value.
  *  non-manifest names keep the legacy `/<stack>/<name>?params` shape. */
 export function buildRoutePath(routes: readonly RouteMeta[], r: Route): string {
 	const meta = routes.find((m) => m.name === r.name)
 	let segs: string[]
 	let rest: Record<string, unknown> = r.params
 	if (meta) {
-		segs = meta.segments.map((s) => {
-			if (!s.startsWith(':')) {
-				return s
+		segs = meta.segments.flatMap((s, i) => {
+			// A mid-path '*' is a literal segment (manifest build warns).
+			const p = s.startsWith('*') && i !== meta.segments.length - 1 ? undefined : segmentParam(s)
+			if (p === undefined) {
+				return [s]
+			}
+
+			const v = r.params[p]
+			if (s.startsWith('*')) {
+				if (v === undefined || v === null || v === '') {
+					return []
+				}
+
+				const enc = encodeRouteParam(v, r.name, p)
+				// '/' in a splat value is a segment boundary; a JSON-encoded
+				// non-scalar stays one encoded segment instead.
+				return enc.startsWith(JSON_PARAM_PREFIX)
+					? [encodeURIComponent(enc)]
+					: enc.split('/').map(encodeURIComponent)
+			}
+
+			if (s.endsWith('?') && (v === undefined || v === null || v === '')) {
+				return [] // optional segment absent — drop it from the path
 			}
 
-			const v = r.params[s.slice(1)]
 			if (v === undefined) {
 				console.warn(`[octane-xplat] route '${r.name}' pushed without path param ${s}`)
 			}
 
-			return encodeURIComponent(encodeRouteParam(v, r.name, s.slice(1)))
+			return [encodeURIComponent(encodeRouteParam(v, r.name, p))]
 		})
 
 		rest = Object.fromEntries(Object.entries(r.params).filter(([k]) => !meta.params.includes(k)))
@@ -526,7 +655,7 @@ export function buildRoutePath(routes: readonly RouteMeta[], r: Route): string {
 		.join('&')
 
 	const path = (r.stack === 'root' ? '' : '/' + r.stack) + '/' + segs.join('/')
-	return (path.replace(/\/+$/, '') || '/') + (q ? '?' + q : '')
+	return (path.replace(/\/+$/, '') || '/') + (q ? '?' + q : '') + (r.hash ? '#' + r.hash : '')
 }
 
 const JSON_PARAM_PREFIX = 'json:'
@@ -611,13 +740,20 @@ export function linkPath(url: string): string {
 /** Match a URL path+query against the manifest into a Route — the shared
  *  half of web's URL parse and native's deep-link handling. Whole-path
  *  match wins ('/demo/x' → root 'demo/:id'); a non-matching first segment
- *  is the stack prefix ('/demos/demo/x' → stack 'demos'). Unmatched names
- *  fall through as literal routes for pre-manifest callers. */
+ *  is the stack prefix ('/demos/demo/x' → stack 'demos'). Whole-path
+ *  includes catch-alls: a root `*` claims every URL, including
+ *  stack-prefixed ones — apps needing named-stack links scope their
+ *  splats under a prefix. Unmatched names fall through as literal
+ *  routes for pre-manifest callers. */
 export function matchUrl(routes: readonly RouteMeta[], url: string): Route | null {
-	// Fragments aren't route params. Split only the first query delimiter;
-	// a later '?' belongs to its value. Reject malformed percent encoding at
-	// this external-input boundary instead of crashing the mounted app.
-	url = url.split('#', 1)[0]
+	// The fragment isn't a route param — it rides the Route's `hash` field so
+	// web can restore scroll to the element it names. Split only the first
+	// query delimiter; a later '?' belongs to its value. Reject malformed
+	// percent encoding at this external-input boundary instead of crashing
+	// the mounted app.
+	const hashAt = url.indexOf('#')
+	const hash = hashAt === -1 ? undefined : url.slice(hashAt + 1)
+	url = hashAt === -1 ? url : url.slice(0, hashAt)
 	const at = url.indexOf('?')
 	const p = at === -1 ? url : url.slice(0, at)
 	const qs = at === -1 ? undefined : url.slice(at + 1)
@@ -652,6 +788,7 @@ export function matchUrl(routes: readonly RouteMeta[], url: string): Route | nul
 		name: m ? m.meta.name : fallbackName,
 		params: { ...query, ...m?.params },
 		presentation: m?.meta.presentation,
+		hash,
 	})
 
 	const root = matchRoute(routes, segs)
@@ -671,10 +808,12 @@ export function matchUrl(routes: readonly RouteMeta[], url: string): Route | nul
 	return finish('root', null, segs[0])
 }
 
-/** Fire a route's `loader` export — prefetch, not a data layer: the
- *  screen's own `query$` reads still own the data, this just warms the
- *  cache before mount. Sync throws and async rejections warn rather
- *  than break navigation. */
+/** Fire a route's `loader` without committing navigation — the opt-in
+ *  prefetch primitive, for warming a `query$` cache ahead of a push an
+ *  app expects to make. This is NOT the navigation loader path: a push
+ *  awaits the loader itself (`commitRoute`) and hands its result to the
+ *  screen as `data`/`error`; the value fired here is discarded. Sync
+ *  throws and async rejections warn rather than break navigation. */
 export function runLoader(routes: readonly RouteMeta[], r: Route): void {
 	const loader = routes.find((m) => m.name === r.name)?.loader
 	if (!loader) {

package/src/route.macos.ts

@@ -65,6 +65,12 @@ export function layoutsFor(name: string): any[] {
 	return layoutChain(routeLayouts, name)
 }
 
+/** The route's declared `ErrorBoundary` export, if any — outlets wrap the
+ *  resolved screen in `RouteBoundary` with it. */
+export function errorBoundaryFor(name: string): any {
+	return metaFor(name)?.errorBoundary
+}
+
 function routeAt(stack: string): Route | null {
 	const entries = stacks.get(stack)
 	return entries?.[entries.length - 1] ?? null
@@ -242,3 +248,5 @@ export function addBackInterceptor(_handler: () => boolean): () => void {
 export function useRouteHead(_route: Route | null): RouteHead | undefined {
 	return undefined
 }
+
+export { layoutsFor as layoutsForRoute }

package/src/route.ts

@@ -31,8 +31,8 @@ import {
 	RouteRedirect,
 } from './route-table'
 
-import { RouteHost } from './route-host.mobile'
-import { modalPresenter } from './modal-presenter.mobile'
+import { RouteHost } from './route-host'
+import { modalPresenter } from './modal-presenter'
 import type { Route, RouteManifest, RouteMeta, ScreenTable } from './props'
 
 export type { Route } from './props'
@@ -97,6 +97,12 @@ export function screenFor(name: string): ScreenTable[string] | undefined {
 	return screens[name]
 }
 
+/** The route's declared `ErrorBoundary` export, if any — outlets wrap the
+ *  resolved screen in `RouteBoundary` with it. */
+export function errorBoundaryFor(name: string): any {
+	return metaFor(name)?.errorBoundary
+}
+
 /** Wrap a screen in its directory `_layout` chain (outermost →
  *  innermost) as a single root component — pushed Pages and modal roots
  *  render this, matching web's outlet wrapping. */
@@ -486,6 +492,8 @@ function commitRoute(r: Route, request: NavigationRequest): void {
 					screen: C,
 					layouts: layoutsForRoute(r.name),
 					params: props,
+					boundary: errorBoundaryFor(r.name),
+					route: r,
 				})
 
 				return page
@@ -549,6 +557,8 @@ function pushModal(frame: Frame, r: Route, C: any): void {
 			screen: C,
 			layouts: layoutsForRoute(r.name),
 			params,
+			boundary: errorBoundaryFor(r.name),
+			route: r,
 		})
 
 		presenter.showModal(host, {

package/src/route.web.ts

@@ -88,6 +88,12 @@ export function screenFor(name: string): ScreenTable[string] | undefined {
 	return screens[name]
 }
 
+/** The route's declared `ErrorBoundary` export, if any — outlets wrap the
+ *  resolved screen in `RouteBoundary` with it. */
+export function errorBoundaryFor(name: string): any {
+	return metaFor(name)?.errorBoundary
+}
+
 /** Directory layouts wrapping a route, outermost → innermost — outlets
  *  wrap their resolved element with these (`_layout.tsrx` files). */
 export function layoutsFor(name: string): any[] {
@@ -129,6 +135,11 @@ function restoreRouteState(): void {
 		if (route) {
 			hydrateRoute(route)
 		}
+
+		// A parsed (never-committed) entry has no prepared scroll state —
+		// a boot hash lands here once the screen mounts.
+		scrollTick += 1
+		settleScroll(true)
 	}
 }
 
@@ -145,8 +156,11 @@ function hydrateRoute(route: Route): void {
 		return
 	}
 
+	// The screen is already mounted — mark the in-flight load so it can
+	// render `pending` until `data`/`error` arrive.
+	route.loaderPending = true
 	const finish = (result: Pick<Route, 'loaderData' | 'loaderError'>) => {
-		const prepared = { ...route, ...result }
+		const prepared = { ...route, ...result, loaderPending: false }
 		let changed = false
 		if (current === route) {
 			current = prepared
@@ -183,23 +197,91 @@ function hydrateRoute(route: Route): void {
 
 const ROUTE_HEAD_ATTR = 'data-octane-xplat-route-head'
 
-// Scroll positions keyed by URL — restored on popstate (native keeps
-// stack pages alive, so only the web leaf needs this). `lastKey` is the
-// outgoing URL: popstate fires after location already changed, so the
-// saved position must be written under the URL we just left.
+// Scroll restoration — the web half of the scroll contract (native keeps
+// stack pages alive, so only this leaf needs it). Positions are keyed by
+// the history-entry id we stamp into history.state — two entries sharing
+// a URL keep independent positions — with the URL (path+query+hash) as
+// the fallback key for entries that predate registration.
+//
+//   push        → top of document, or the element the route's `hash` names
+//   pop/forward → the position saved for that entry (then hash, then top)
+//   modal push  → overlay — the underlying position is left untouched
+//
+// `lastKey` tracks the outgoing entry: popstate fires after location
+// already changed, so the position must be written under the entry we
+// just left.
+if (typeof history !== 'undefined' && 'scrollRestoration' in history) {
+	// The browser's own scroll restoration would race ours on traversal
+	// and reload — the contract above owns scroll instead.
+	history.scrollRestoration = 'manual'
+}
+
 const scrollPositions = new Map<string, number>()
-let lastKey = location.pathname + location.search
-const scrollKey = () => location.pathname + location.search
+const scrollKey = () =>
+	(history.state?.__octaneXplatEntry as string | undefined) ??
+	location.pathname + location.search + location.hash
+
+let lastKey = scrollKey()
 const saveScroll = () => scrollPositions.set(lastKey, window.scrollY)
-const restoreScroll = () => {
-	const y = scrollPositions.get(scrollKey())
-	if (y !== undefined) {
-		requestAnimationFrame(() => window.scrollTo(0, y))
+
+function scrollToHash(hash: string): boolean {
+	const id = hash.slice(1)
+	if (!id) {
+		return false
 	}
+
+	let decoded = id
+	try {
+		decoded = decodeURIComponent(id)
+	} catch {
+		// keep the raw fragment — malformed input just misses the lookup
+	}
+
+	const target = document.getElementById(decoded)
+	if (!target) {
+		return false
+	}
+
+	target.scrollIntoView()
+	return true
+}
+
+// Settles carry the navigation they're for: `scrollTick` advances on every
+// commit/traversal, and a queued settle drops itself when a newer navigation
+// superseded it — otherwise a settle scheduled just before a push could fire
+// on the new entry and fight the push's own scroll. Key and hash are
+// captured at schedule time for the same reason — popstate has already
+// moved `location` when the handler runs, but a queued settle can outlive
+// one more commit.
+let scrollTick = 0
+
+// Defer to rAF so the newly resolved screen has mounted before we measure
+// or scroll it — a still-mounting hash target simply misses to top.
+function settleScroll(restore: boolean): void {
+	const tick = scrollTick
+	const key = scrollKey()
+	const hash = location.hash
+	requestAnimationFrame(() => {
+		if (tick !== scrollTick) {
+			return
+		}
+
+		if (restore) {
+			const y = scrollPositions.get(key)
+			if (y !== undefined) {
+				window.scrollTo(0, y)
+				return
+			}
+		}
+
+		if (!scrollToHash(hash)) {
+			window.scrollTo(0, 0)
+		}
+	})
 }
 
 function parse(): Route | null {
-	return matchUrl(routes, location.pathname + location.search)
+	return matchUrl(routes, location.pathname + location.search + location.hash)
 }
 
 function read(): Route | null {
@@ -328,9 +410,10 @@ function commitRoute(r: Route, request: NavigationRequest): void {
 		return
 	}
 
-	saveScroll()
 	read()
-	// Include the entry we are leaving, even if it was the initial URL.
+	// Include the entry we are leaving, even if it was the initial URL —
+	// the replace also mints its entry id, so its scroll position saves
+	// under the same key a later popstate will look up.
 	history.replaceState(
 		{
 			...history.state,
@@ -340,6 +423,9 @@ function commitRoute(r: Route, request: NavigationRequest): void {
 		'',
 	)
 
+	lastKey = scrollKey()
+	saveScroll()
+
 	historyDepth += 1
 	if (route.presentation === 'modal') {
 		modalRoute = route
@@ -358,6 +444,14 @@ function commitRoute(r: Route, request: NavigationRequest): void {
 
 	applyHead(modalRoute ?? current ?? null)
 	emit()
+	// A push starts at the top — or the hash target — of the new document.
+	// A modal overlays the current entry instead, so it leaves the
+	// underlying position untouched. The tick still advances so a stale
+	// settle doesn't fire on the modal entry.
+	scrollTick += 1
+	if (route.presentation !== 'modal') {
+		settleScroll(false)
+	}
 }
 
 function presentationFor(name: string): Route['presentation'] {
@@ -389,16 +483,27 @@ export function addBackInterceptor(_fn: () => boolean): () => void {
 	return () => {}
 }
 
-window.addEventListener('popstate', () => {
+// Singletoned like the native back-press wiring: under vite HMR this
+// module's state resets but its popstate listener must not duplicate —
+// the handler delegates through a slot so a reloaded module graph swaps
+// in fresh closures instead of double-settling.
+const host = window as any
+host.__octaneXplatPopstate = () => {
 	navigationRequests.invalidate('history')
 	saveScroll()
 	historyDepth = history.state?.__octaneXplatDepth ?? 0
 	lastKey = scrollKey()
 	restoreRouteState()
 	applyHead(modalRoute ?? current ?? null)
-	restoreScroll()
+	scrollTick += 1
+	settleScroll(true)
 	emit()
-})
+}
+
+if (!host.__octaneXplatRouteWired) {
+	host.__octaneXplatRouteWired = true
+	window.addEventListener('popstate', () => host.__octaneXplatPopstate?.())
+}
 
 /** Current route if it targets `stack`, else null. */
 export function routeFor(stack: string): Route | null {

package/src/safe-url.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import { sanitizeUrl } from './safe-url'
+
+describe('sanitizeUrl', () => {
+	it('blocks script and HTML data schemes, including control-character obfuscation', () => {
+		expect(sanitizeUrl('javascript:alert(1)')).toBeNull()
+		expect(sanitizeUrl('java\nscript:alert(1)')).toBeNull()
+		expect(sanitizeUrl('data:text/html,<script>')).toBeNull()
+	})
+
+	it('keeps ordinary web URLs unchanged', () => {
+		expect(sanitizeUrl('https://example.com/path?q=1')).toBe('https://example.com/path?q=1')
+	})
+})