@markless/router 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -79,6 +79,31 @@ declare function transformRequestFileSource(fileId: string, sourceText: string):
 //#region src/route-renderer.d.ts
 declare function startRouteUpdateRenderer(document?: Document): void;
 //#endregion
+//#region src/spa-navigation.d.ts
+type MarklessRouterNavigationRuntime = Pick<Navigation, 'addEventListener' | 'navigate'>;
+interface MarklessRouterNavigationWindow {
+  readonly document: Document;
+  readonly location: Location;
+  navigation?: MarklessRouterNavigationRuntime;
+  addEventListener(type: 'click', listener: (event: MouseEvent) => void, options?: boolean | AddEventListenerOptions): void;
+}
+interface MarklessRouterNavigationPolyfillModule {
+  applyPolyfill(options: {
+    readonly interceptEvents: boolean;
+    readonly window: MarklessRouterNavigationWindow;
+  }): unknown;
+}
+interface StartSpaNavigationOptions {
+  readonly documentModuleLoader?: () => Promise<unknown>;
+  readonly loadPolyfill?: () => Promise<MarklessRouterNavigationPolyfillModule>;
+  readonly pageModuleLoaders: Record<string, () => Promise<unknown>>;
+  readonly preloadRouteModule?: (file: string) => unknown;
+  readonly routeFileIds: readonly string[];
+  readonly window?: MarklessRouterNavigationWindow;
+}
+declare function __marklessRouterStartSpaNavigation(options: StartSpaNavigationOptions): Promise<void>;
+declare function ensureNavigationRuntime(runtimeWindow?: MarklessRouterNavigationWindow, loadPolyfill?: () => Promise<MarklessRouterNavigationPolyfillModule>): Promise<MarklessRouterNavigationRuntime>;
+//#endregion
 //#region src/route-state.d.ts
 declare const MARKLESS_ROUTER_ROUTE_EVENT = "marklessrouternavigate";
 interface RouteState {
@@ -172,4 +197,4 @@ declare const Link: ((props?: LinkProps) => unknown) & {
   };
 };
 //#endregion
-export { type ApiRequestFileCache, type ApiRequestFileMethod, type ApiRequestFileRoute, AppLocals, DefaultLinkProps, EndpointHttpContext, Html, HttpContext, HttpResponse, Link, LinkNavigationProps, LinkProps, MARKLESS_ROUTER_ROUTE_EVENT, MarklessRouterGeneratedRoutes, MiddlewareHttpContext, PageProps, type RequestFileDefaultExport, type RequestFileDiagnostic, type RequestFileDiagnosticCode, type RequestFileParam, type RequestFileParseResult, type RequestFileTransformResult, type RouteDocumentModule, type RouteManifest, type RouteManifestMatch, type RouteManifestParam, type RouteManifestRoute, type RouteManifestStatusPages, type RoutePageModule, type RouteState, type RouteUpdate, __marklessCreateHttpContext, buildRouteManifestFromFileIds, dispatchRouteUpdate, matchRouteManifest, normalizeRequestFileId, normalizeRequestPathname, normalizeRouteFileId, parseRequestFile, routePageProps, startRouteUpdateRenderer, transformRequestFileSource };
+export { type ApiRequestFileCache, type ApiRequestFileMethod, type ApiRequestFileRoute, AppLocals, DefaultLinkProps, EndpointHttpContext, Html, HttpContext, HttpResponse, Link, LinkNavigationProps, LinkProps, MARKLESS_ROUTER_ROUTE_EVENT, MarklessRouterGeneratedRoutes, MiddlewareHttpContext, PageProps, type RequestFileDefaultExport, type RequestFileDiagnostic, type RequestFileDiagnosticCode, type RequestFileParam, type RequestFileParseResult, type RequestFileTransformResult, type RouteDocumentModule, type RouteManifest, type RouteManifestMatch, type RouteManifestParam, type RouteManifestRoute, type RouteManifestStatusPages, type RoutePageModule, type RouteState, type RouteUpdate, __marklessCreateHttpContext, __marklessRouterStartSpaNavigation, buildRouteManifestFromFileIds, dispatchRouteUpdate, ensureNavigationRuntime, matchRouteManifest, normalizeRequestFileId, normalizeRequestPathname, normalizeRouteFileId, parseRequestFile, routePageProps, startRouteUpdateRenderer, transformRequestFileSource };

package/dist/index.js

@@ -60,6 +60,157 @@ async function renderRouteUpdate(document, update) {
 	}
 }
 //#endregion
+//#region src/spa-navigation.ts
+const STARTED = "__marklessRouterSpaNavigationStarted";
+const LINK_ATTRIBUTE = "data-markless-router-link";
+const REPLACE_ATTRIBUTE = "data-markless-router-replace";
+const SCROLL_ATTRIBUTE = "data-markless-router-scroll";
+const LINK_INFO = "__marklessRouterLink";
+function hashRoutePath(url) {
+	return url.hash.startsWith("#/") ? url.hash.slice(1) : void 0;
+}
+function routePathname(url, _context) {
+	return hashRoutePath(url) ?? url.pathname;
+}
+async function __marklessRouterStartSpaNavigation(options) {
+	const runtimeWindow = options.window ?? browserWindow();
+	const state = runtimeWindow;
+	if (state[STARTED]) return;
+	state[STARTED] = true;
+	const context = {
+		documentModuleLoader: options.documentModuleLoader,
+		manifest: buildRouteManifestFromFileIds(options.routeFileIds),
+		pageModuleLoaders: options.pageModuleLoaders,
+		preloadRouteModule: options.preloadRouteModule,
+		window: runtimeWindow
+	};
+	const navigation = await ensureNavigationRuntime(runtimeWindow, options.loadPolyfill);
+	runtimeWindow.addEventListener("click", (event) => handleLinkClick(event, context, navigation), true);
+	navigation.addEventListener("navigate", (event) => {
+		handleNavigateEvent(event, context);
+	});
+	{
+		const bootUrl = parseSameOriginUrl(runtimeWindow.location.href, runtimeWindow.location.href);
+		const bootHashPath = bootUrl ? hashRoutePath(bootUrl) : void 0;
+		if (bootUrl && bootHashPath && matchRouteManifest(bootHashPath, context.manifest)) renderRoute(bootUrl, context);
+	}
+}
+async function ensureNavigationRuntime(runtimeWindow = browserWindow(), loadPolyfill) {
+	if (!runtimeWindow.navigation) {
+		const { applyPolyfill } = await (loadPolyfill?.() ?? import("@virtualstate/navigation"));
+		runtimeWindow.navigation = applyPolyfill({
+			interceptEvents: false,
+			window: runtimeWindow
+		});
+	}
+	return runtimeWindow.navigation;
+}
+function handleNavigateEvent(event, context) {
+	const url = routeUrl(event, context);
+	if (!url) return false;
+	event.intercept({
+		focusReset: "after-transition",
+		scroll: navigationScroll(event),
+		handler: () => renderRoute(url, context, event.signal)
+	});
+	return true;
+}
+async function renderRoute(url, context, signal) {
+	if (signal?.aborted) return;
+	const match = matchRouteManifest(routePathname(url, context), context.manifest);
+	const loadPageModule = match && context.pageModuleLoaders[match.route.file];
+	if (!match || !loadPageModule) {
+		if (hashRoutePath(url) !== void 0) warnUnknownHashRoute(url);
+		context.window.location.assign(url.href);
+		return;
+	}
+	preloadRouteModule(context, match.route.file);
+	const [page, document] = await Promise.all([loadPageModule(), context.documentModuleLoader?.()]);
+	if (signal?.aborted) return;
+	const update = {
+		document,
+		page,
+		route: {
+			file: match.route.file,
+			params: match.params,
+			status: 200,
+			url: url.href
+		},
+		signal
+	};
+	if (!(context.window.document["__marklessRouterRouteRendererStarted"] === true)) {
+		dispatchRouteUpdate(context.window.document, update);
+		return;
+	}
+	await new Promise((resolve) => {
+		dispatchRouteUpdate(context.window.document, {
+			...update,
+			onRendered: resolve
+		});
+	});
+}
+function warnUnknownHashRoute(url) {
+	if (!import.meta.env?.DEV) return;
+	console.error(`MARKLESS_ROUTER_UNKNOWN_HASH_ROUTE: Navigation to "${url.hash}" matched no route file. Hash URLs cannot fall back to a server document load, so this navigation does nothing. Add a page for "${url.hash.slice(1)}" or fix the link href.`);
+}
+function handleLinkClick(event, context, navigation) {
+	if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.altKey || event.ctrlKey || event.shiftKey) return;
+	const anchor = sourceAnchor(event);
+	if (!anchor || !anchor.hasAttribute(LINK_ATTRIBUTE) || !isEligibleLink(anchor)) return;
+	const url = parseSameOriginUrl(anchor.href, context.window.location.href);
+	const match = url && matchRouteManifest(routePathname(url, context), context.manifest);
+	if (!match) return;
+	preloadRouteModule(context, match.route.file);
+	event.preventDefault();
+	navigation.navigate(url.href, {
+		history: anchor.hasAttribute(REPLACE_ATTRIBUTE) ? "replace" : "push",
+		info: {
+			[LINK_INFO]: true,
+			scroll: anchor.getAttribute(SCROLL_ATTRIBUTE) === "manual" ? "manual" : void 0
+		}
+	});
+}
+function preloadRouteModule(context, file) {
+	try {
+		context.preloadRouteModule?.(file);
+	} catch {}
+}
+function routeUrl(event, context) {
+	const destination = parseSameOriginUrl(event.destination.url, context.window.location.href);
+	const hashRouteNavigation = event.hashChange === true && !!destination && hashRoutePath(destination) !== void 0;
+	if (!isMarklessRouterNavigation(event) && !hashRouteNavigation || event.canIntercept === false || event.navigationType === "reload" || event.hashChange && !hashRouteNavigation || event.downloadRequest != null || event.formData != null) return;
+	const matched = destination && matchRouteManifest(routePathname(destination), context.manifest) ? destination : void 0;
+	if (!matched && hashRouteNavigation && destination) warnUnknownHashRoute(destination);
+	return matched;
+}
+function isMarklessRouterNavigation(event) {
+	return event.info?.[LINK_INFO] === true || event.navigationType === "traverse";
+}
+function navigationScroll(event) {
+	const info = event.info;
+	return info?.[LINK_INFO] === true && info.scroll === "manual" ? "manual" : "after-transition";
+}
+function parseSameOriginUrl(href, base) {
+	try {
+		const current = new URL(base);
+		const url = new URL(href, current);
+		return url.origin === current.origin ? url : void 0;
+	} catch {
+		return;
+	}
+}
+function sourceAnchor(event) {
+	const target = event.composedPath?.()[0] ?? event.target;
+	return target?.closest?.("a[href]") ?? target?.parentElement?.closest?.("a[href]");
+}
+function isEligibleLink(anchor) {
+	const target = anchor.getAttribute("target");
+	return (!target || target === "_self") && !anchor.hasAttribute("download") && !anchor.relList?.contains("external");
+}
+function browserWindow() {
+	return window;
+}
+//#endregion
 //#region src/index.ts
 function __marklessCreateHttpContext(event) {
 	const context = event.context ?? {};
@@ -120,4 +271,4 @@ function escapeHtml(value) {
 	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
 }
 //#endregion
-export { Html, Link, MARKLESS_ROUTER_ROUTE_EVENT, __marklessCreateHttpContext, buildRouteManifestFromFileIds, dispatchRouteUpdate, matchRouteManifest, normalizeRequestFileId, normalizeRequestPathname, normalizeRouteFileId, parseRequestFile, routePageProps, startRouteUpdateRenderer, transformRequestFileSource };
+export { Html, Link, MARKLESS_ROUTER_ROUTE_EVENT, __marklessCreateHttpContext, __marklessRouterStartSpaNavigation, buildRouteManifestFromFileIds, dispatchRouteUpdate, ensureNavigationRuntime, matchRouteManifest, normalizeRequestFileId, normalizeRequestPathname, normalizeRouteFileId, parseRequestFile, routePageProps, startRouteUpdateRenderer, transformRequestFileSource };

package/dist/vite.js

@@ -851,7 +851,7 @@ const ROUTE_HREF_ID = "virtual:markless-router/route-href";
 const ROUTER_OPTIONS_ID = "virtual:markless-router/options";
 const PUBLIC_VIRTUAL_MODULE_ID_RE = /^virtual:markless-router\/(?:routes|client-entry|resume-entry|resume-entry-path|navigation-entry|navigation-entry-path|route-preloads|server-entry|route-href|options)(?:\?.*)?$/;
 const VITE_PLUGIN_FILE = decodePath(parseURL(import.meta.url).pathname);
-const VIRTUAL_ENTRY_DIR = VITE_PLUGIN_FILE.endsWith(".ts") ? join(dirname(VITE_PLUGIN_FILE), "entries") : join(dirname(dirname(VITE_PLUGIN_FILE)), "entries");
+const VIRTUAL_ENTRY_DIR = VITE_PLUGIN_FILE.endsWith(".ts") ? join(dirname(VITE_PLUGIN_FILE), "entries") : join(dirname(dirname(VITE_PLUGIN_FILE)), "src/vite/entries");
 const DEFAULT_WATCH_IGNORES = [
 	"**/.nitro/**",
 	"**/.output/**",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markless/router",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Markless router: client-side navigation with SSR streaming and build-time preload maps.",
   "license": "MIT",
   "repository": {
@@ -12,7 +12,8 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "src/vite/entries"
   ],
   "type": "module",
   "sideEffects": false,
@@ -54,8 +55,8 @@
     "pathe": "^2.0.3",
     "satteri": "0.6.3",
     "ufo": "^1.6.4",
-    "@markless/bundler": "0.1.0",
-    "@markless/web": "0.1.0"
+    "@markless/bundler": "0.1.1",
+    "@markless/web": "0.1.1"
   },
   "peerDependencies": {
     "vite": "8.0.16"

package/src/vite/entries/client-entry.ts

@@ -0,0 +1,67 @@
+// Package specifiers only: this file ships as source in the tarball and is
+// compiled in the CONSUMER app's module graph (so import.meta.glob resolves
+// against the app root) — relative paths into src/ would escape the package.
+import { createRouteDiscovery } from '@markless/router/vite/runtime/create-route-discovery';
+import {
+	__marklessRouterStartSpaNavigation,
+	buildRouteManifestFromFileIds,
+	ensureNavigationRuntime,
+	matchRouteManifest,
+	startRouteUpdateRenderer,
+} from '@markless/router';
+import { preloadRouteModule } from 'virtual:markless-router/route-preloads';
+
+const routeDiscovery = createRouteDiscovery(
+	import.meta.glob(['/pages/**/*.tsrx', '/pages/**/*.mdx']),
+);
+
+export const pageModules = routeDiscovery.pageModuleLoaders;
+export const routeFileIds = routeDiscovery.routeFileIds;
+const routeManifest = buildRouteManifestFromFileIds(routeFileIds);
+
+void __marklessRouterStartSpaNavigation({
+	pageModuleLoaders: pageModules,
+	preloadRouteModule,
+	routeFileIds,
+});
+startRouteUpdateRenderer(document);
+
+export async function navigateMarklessRouterLink(input: {
+	readonly href: string;
+	readonly replace?: boolean;
+	readonly scroll?: 'manual';
+}) {
+	const url = parseSameOriginUrl(input.href, window.location.href);
+	const match = url && matchRouteManifest(url.pathname, routeManifest);
+	if (!url || !match) {
+		window.location.assign(input.href);
+		return;
+	}
+
+	startRouteUpdateRenderer(document);
+	preloadRouteModule(match.route.file);
+	await __marklessRouterStartSpaNavigation({
+		pageModuleLoaders: pageModules,
+		preloadRouteModule,
+		routeFileIds,
+		window,
+	});
+	const navigation = await ensureNavigationRuntime(window);
+	navigation.navigate(url.href, {
+		history: input.replace ? 'replace' : 'push',
+		info: {
+			__marklessRouterLink: true,
+			scroll: input.scroll,
+		},
+	});
+}
+
+function parseSameOriginUrl(href: string, base: string): URL | undefined {
+	try {
+		const current = new URL(base);
+		const url = new URL(href, current);
+		return url.origin === current.origin ? url : undefined;
+	} catch {
+		return undefined;
+	}
+}

package/src/vite/entries/resume-entry.ts

@@ -0,0 +1,42 @@
+const mdxPageModuleLoaders = import.meta.glob('/pages/**/*.mdx');
+const tsrxResumeModuleLoaders = import.meta.glob('/pages/**/*.tsrx', {
+	query: '?markless-resume',
+});
+
+export async function resumeContainerEvent(input: {
+	readonly root: ParentNode;
+	readonly [key: string]: unknown;
+}) {
+	const file = routeFileFromRoot(input.root);
+	const loadRouteResumeModule = file && routeResumeModuleLoader(file);
+	const routeResumeModule = loadRouteResumeModule ? await loadRouteResumeModule() : undefined;
+	const resume = (routeResumeModule as RouteResumeModule | undefined)?.resumeContainerEvent;
+	if (typeof resume !== 'function') {
+		throw new Error(`Markless Router could not resume route module: ${file ?? '<unknown>'}`);
+	}
+	await resume(input);
+}
+
+interface RouteResumeModule {
+	readonly resumeContainerEvent?: (input: unknown) => unknown;
+}
+
+function routeResumeModuleLoader(file: string): (() => Promise<unknown>) | undefined {
+	const loaders = file.endsWith('.mdx') ? mdxPageModuleLoaders : tsrxResumeModuleLoaders;
+	return loaders[file] ?? loaders[`/${file}`];
+}
+
+function routeFileFromRoot(root: ParentNode): string | undefined {
+	const script = root.querySelector?.('script[type="@markless/core/route"]');
+	const text = script?.textContent;
+	if (!text) {
+		return undefined;
+	}
+
+	try {
+		const route = JSON.parse(text) as { readonly file?: unknown };
+		return typeof route.file === 'string' ? route.file : undefined;
+	} catch {
+		return undefined;
+	}
+}

package/src/vite/entries/route-discovery.ts

@@ -0,0 +1,8 @@
+import { createRouteDiscovery } from '@markless/router/vite/runtime/create-route-discovery';
+
+const routeDiscovery = createRouteDiscovery(
+	import.meta.glob(['/pages/**/*.tsrx', '/pages/**/*.mdx']),
+);
+
+export const pageModuleLoaders = routeDiscovery.pageModuleLoaders;
+export const routeFileIds = routeDiscovery.routeFileIds;

package/src/vite/entries/route-href.ts

@@ -0,0 +1,35 @@
+const routeParamPattern = /\[\.\.\.([A-Za-z_$][\w$]*)\]|\[([A-Za-z_$][\w$]*)\]/g;
+
+export function __marklessRouteHref(
+	pattern: string,
+	params: Readonly<Record<string, unknown>>,
+): string {
+	return pattern.replace(routeParamPattern, (_match, catchAll, dynamic) => {
+		const name = catchAll || dynamic;
+		const value = params?.[name];
+
+		if (catchAll) {
+			return encodeCatchAllParam(pattern, value);
+		}
+
+		if (value === null || value === undefined) {
+			throw new Error(`Typed route error: ${pattern} requires params:\n- ${name}`);
+		}
+
+		return encodeURIComponent(String(value));
+	});
+}
+
+function encodeCatchAllParam(pattern: string, value: unknown): string {
+	const segments = Array.isArray(value)
+		? value
+		: value === null || value === undefined
+			? []
+			: String(value).split('/');
+
+	if (segments.length === 0 || segments.some((segment) => String(segment) === '')) {
+		throw new Error(`Typed route error: ${pattern} requires a non-empty catch-all param.`);
+	}
+
+	return segments.map((segment) => encodeURIComponent(String(segment))).join('/');
+}

package/src/vite/entries/server-entry.ts

@@ -0,0 +1,22 @@
+import { createServerEntry } from '@markless/router/vite/runtime/create-server-entry';
+import { resumeEntryPath } from 'virtual:markless-router/resume-entry-path';
+import { navigationEntryPath } from 'virtual:markless-router/navigation-entry-path';
+import {
+	routeModulePreloads,
+	routeSsrModulePreloads,
+} from 'virtual:markless-router/route-preloads';
+import { pageModuleLoaders, routeFileIds } from 'virtual:markless-router/routes';
+
+const documentModuleLoaders = import.meta.glob(['/document.tsrx']);
+const entry = createServerEntry({
+	resumeEntryPath,
+	navigationEntryPath,
+	routeModulePreloads,
+	routeSsrModulePreloads,
+	documentModuleLoader: documentModuleLoaders['/document.tsrx'],
+	pageModuleLoaders,
+	routeFileIds,
+});
+
+export const fetch = entry.fetch;
+export default entry;