@octane-xplat/ui 0.7.3 → 0.10.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
@@ -30,14 +32,93 @@
  *  fallback (rank = prefer.length). Web callers pass ['web']; mobile
  *  callers pass the running OS first. */
 
-import type { Route, RouteManifest, RouteMeta, RouteSpec, RouteSpecSet } from './props'
+import type {
+	Route,
+	RouteManifest,
+	RouteManifestJson,
+	RouteMeta,
+	RouteSpec,
+	RouteSpecSet,
+	SpecRouteInfo,
+} from './props'
 
 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)$/
 // `settings+modal.tsrx` → route 'settings' presented modally by default.
 const PRESENT = /\+(modal|fade|push)$/
 
+/** Loader for a `dataMode: 'baked'` route — resolves the name out of its
+ *  owning manifest's `baked` map at push time. The map is assigned after
+ *  the manifest is built (generated glue) or passed in (RouteSpecSet), so
+ *  the lookup reads it lazily. A missing entry throws, landing as the
+ *  screen's `error` prop like a live loader rejection. */
+function bakedLookup(manifest: () => RouteManifest | undefined, name: string) {
+	return () => {
+		const baked = manifest()?.baked
+		if (baked && Object.prototype.hasOwnProperty.call(baked, name)) {
+			return baked[name]
+		}
+
+		throw new Error(
+			`[octane-xplat] baked route '${name}' has no baked data — run \`xplat routes\` to regenerate`,
+		)
+	}
+}
+
 /** Internal error carrier used by the public `redirect()` helper. Keeping
  * this in the shared route table gives both platform leaves the same guard
  * behavior without importing a platform runtime. */
@@ -62,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) {
@@ -93,8 +176,13 @@ export function deriveRouteManifest(
 	const layouts: Record<string, any> = {}
 	const loaders: RouteManifest['loaders'] = {}
 	const warned = new Set<string>()
+	const self: { m?: RouteManifest } = {}
 
 	for (const key of Object.keys(files).sort()) {
+		if (LOADER_FILE.test(key)) {
+			continue
+		}
+
 		let rel = key.replace(/^\.?\//, '')
 		if (rel.startsWith(prefix)) {
 			rel = rel.slice(prefix.length)
@@ -141,22 +229,32 @@ 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
+		}
+
 		const loader = files[key]?.loader
-		if (typeof loader === 'function') {
+		if (meta.dataMode === 'baked') {
+			meta.loader = bakedLookup(() => self.m, name)
+			if (typeof loader === 'function') {
+				console.warn(
+					`[octane-xplat] baked route '${name}' also exports a loader — move it to a .loader.ts sibling so its imports stay out of the bundle`,
+				)
+			}
+		} else if (typeof loader === 'function') {
 			meta.loader = loader
 		}
 
@@ -165,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')
@@ -203,30 +306,32 @@ export function deriveRouteManifest(
 	// Most-specific patterns first — 'demo/new' must beat 'demo/:id'.
 	routes.sort(bySpecificity)
 
-	return { screens, routes, layouts, loaders }
+	const manifest = { screens, routes, layouts, loaders }
+	self.m = manifest
+	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()
@@ -242,8 +347,15 @@ const mergeWarned = new Set<string>()
  *  from their own sources, e.g. `readdirSync` over a content dir). Each
  *  spec's `path` uses the route-dir vocabulary; `layouts` keys are path
  *  prefixes playing the `_layout` role. Same-name duplicates inside the
- *  set keep the later entry with a warn, matching merge precedence. */
-export function defineRoutes(input: readonly RouteSpec[] | RouteSpecSet): RouteManifest {
+ *  set keep the later entry with a warn, matching merge precedence.
+ *
+ *  The return is branded with the spec-derived route types — read them
+ *  with `ManifestRouteParams`/`ManifestRouteNames`/
+ *  `ManifestRoutePresentations` to merge programmatic names into the
+ *  app's typed navigation surface (`RouteName | …`, `RouteParams & …`). */
+export function defineRoutes<const Specs extends readonly RouteSpec[]>(
+	input: Specs | (Omit<RouteSpecSet, 'routes'> & { routes: Specs }),
+): RouteManifest & SpecRouteInfo<Specs> {
 	const set = (Array.isArray(input) ? { routes: input } : input) as RouteSpecSet
 	const specs = set.routes
 	const extra = set.layouts
@@ -252,6 +364,7 @@ export function defineRoutes(input: readonly RouteSpec[] | RouteSpecSet): RouteM
 	const layouts: RouteManifest['layouts'] = {}
 	const metas = new Map<string, RouteMeta>()
 	const warned = new Set<string>()
+	const self: { m?: RouteManifest } = {}
 
 	for (const [key, layout] of Object.entries(extra ?? {})) {
 		const dir = key.replace(/^\/+|\/+$/g, '')
@@ -268,12 +381,25 @@ export function defineRoutes(input: readonly RouteSpec[] | RouteSpecSet): RouteM
 		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,
 		}
 
-		if (spec.loader) {
+		warnOnStraySplat(segments, meta.file)
+
+		if (spec.dataMode) {
+			meta.dataMode = spec.dataMode
+		}
+
+		if (spec.dataMode === 'baked') {
+			meta.loader = bakedLookup(() => self.m, name)
+			if (spec.loader) {
+				console.warn(
+					`[octane-xplat] baked route '${name}' also carries a loader — bake it in the host and pass the result via 'baked' so its code stays out of the bundle`,
+				)
+			}
+		} else if (spec.loader) {
 			meta.loader = spec.loader
 		}
 
@@ -281,6 +407,10 @@ export function defineRoutes(input: readonly RouteSpec[] | RouteSpecSet): RouteM
 			meta.beforeLoad = spec.beforeLoad
 		}
 
+		if (spec.errorBoundary) {
+			meta.errorBoundary = spec.errorBoundary
+		}
+
 		if (spec.head) {
 			meta.head = spec.head
 		}
@@ -296,6 +426,7 @@ export function defineRoutes(input: readonly RouteSpec[] | RouteSpecSet): RouteM
 			console.warn(
 				`[octane-xplat] route '${name}' has no component — 'screen' must be a component function, not a module`,
 			)
+
 			continue
 		}
 
@@ -311,7 +442,9 @@ export function defineRoutes(input: readonly RouteSpec[] | RouteSpecSet): RouteM
 		}
 	}
 
-	return { screens, routes, layouts, loaders }
+	const manifest = { screens, routes, layouts, loaders, baked: set.baked }
+	self.m = manifest
+	return manifest as RouteManifest & SpecRouteInfo<Specs>
 }
 
 /** Compose manifests into one — file-derived base plus any number of
@@ -323,10 +456,12 @@ export function defineRoutes(input: readonly RouteSpec[] | RouteSpecSet): RouteM
 export function mergeRouteManifests(...manifests: RouteManifest[]): RouteManifest {
 	const screens: RouteManifest['screens'] = {}
 	const layouts: RouteManifest['layouts'] = {}
+	const baked: NonNullable<RouteManifest['baked']> = {}
 	const winners = new Map<string, RouteMeta>()
 
 	for (const m of manifests) {
 		Object.assign(layouts, m.layouts)
+		Object.assign(baked, m.baked)
 		// Screen-table entries without a RouteMeta still register — a screen
 		// is pushable by name even without a URL pattern.
 		Object.assign(screens, m.screens)
@@ -351,60 +486,160 @@ export function mergeRouteManifests(...manifests: RouteManifest[]): RouteManifes
 		}
 	}
 
-	return { screens, routes, layouts, loaders }
+	return { screens, routes, layouts, loaders, baked }
+}
+
+/** Serialize a manifest to the normalized `RouteManifestJson` shape — the
+ *  same list `xplat routes` emits for file routes, produced here for
+ *  programmatic/merged manifests so hosts consume one schema. */
+export function manifestToJson(manifest: RouteManifest): RouteManifestJson {
+	return {
+		version: 1,
+		layouts: Object.keys(manifest.layouts).sort(),
+		screens: Object.keys(manifest.screens).sort(),
+		routes: manifest.routes.map((meta) => {
+			const segs = meta.name.split('/')
+			const layoutDirs: string[] = manifest.layouts[''] ? [''] : []
+			for (let i = 1; i < segs.length; i++) {
+				const d = segs.slice(0, i).join('/')
+				if (manifest.layouts[d]) {
+					layoutDirs.push(d)
+				}
+			}
+
+			return {
+				name: meta.name,
+				path: meta.name === 'index' ? '' : meta.segments.join('/'),
+				params: [...meta.params],
+				...(meta.presentation ? { presentation: meta.presentation } : {}),
+				...(meta.dataMode ? { dataMode: meta.dataMode } : {}),
+				layouts: layoutDirs,
+				source: meta.file,
+				loader: !!meta.loader,
+				guard: !!meta.beforeLoad,
+				head: !!meta.head,
+				errorBoundary: !!meta.errorBoundary,
+			}
+		}),
+	}
 }
 
 /** 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 }
 		}
+	}
+
+	return null
+}
 
-		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
+/** 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)))
@@ -420,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:'
@@ -505,12 +740,41 @@ 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 {
-	const [p, qs] = url.split('?')
+	// 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)
 	const segs = p.split('/').filter(Boolean)
-	const query = parseQueryString(qs)
+	let query: Record<string, unknown>
+	try {
+		// Use the decoded value: production optimizers can drop an unused
+		// builtin call even though malformed input makes it throw.
+		if (!decodeURIComponent(p)) {
+			return null
+		}
+
+		query = parseQueryString(qs)
+	} catch (error) {
+		if (error instanceof URIError) {
+			return null
+		}
+
+		throw error
+	}
+
 	if (!segs.length) {
 		return null
 	}
@@ -524,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)
@@ -543,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) {