@markless/router 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markless/router",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Markless router: client-side navigation with SSR streaming and build-time preload maps.",
   "license": "MIT",
   "repository": {
@@ -64,11 +64,11 @@
     "pathe": "^2.0.3",
     "satteri": "0.6.3",
     "ufo": "^1.6.4",
-    "@markless/bundler": "0.5.0",
-    "@markless/web": "0.5.0"
+    "@markless/web": "0.7.0",
+    "@markless/bundler": "0.7.0"
   },
   "devDependencies": {
-    "@markless/analyzer": "0.5.0"
+    "@markless/analyzer": "0.7.0"
   },
   "peerDependencies": {
     "typescript": "^5.9.3",

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

@@ -3,17 +3,24 @@ import type { ModulePreloadInput } from '@markless/web/render-to-string';
 
 export interface FragmentNavigationConfig {
 	readonly entry: string;
+	readonly entryImports: readonly string[];
 	readonly linkAttribute: string;
 	readonly prefetchAttribute: string;
 	readonly replaceAttribute: string;
 	readonly scrollAttribute: string;
 	readonly routeScriptType: string;
+	readonly servedHtmlAttributesProperty: string;
 	readonly retireProperty: string;
 	readonly streamExecutorGlobal: string;
 	readonly streamedArmSelector: string;
-	readonly requestHeader: string;
+	readonly requestPrefix: string;
 	readonly regionEndMarker: string;
 	readonly appendMarker: string;
+	// Close and open the page's nodes when the document's own element is the container; what is outside is the document's.
+	readonly pageEndComment: string;
+	readonly pageStartComment: string;
+	// The container's own attributes, never carried from the leaving page's element to the next one.
+	readonly containerAttributes: readonly [container: string, paths: string];
 	// 'document' apps swap the whole body: their shell renders from the request URL.
 	readonly documentLoads: boolean;
 	// A mouse fetches after resting this long on a link; press, focus and touch fetch at once.
@@ -23,7 +30,7 @@ export interface FragmentNavigationConfig {
 	readonly prefetchConnections: number;
 	// Paths the server answers with endpoints, not pages: never fetched before a click or as a fragment.
 	readonly endpointPrefixes: readonly string[];
-	// At most this many visible-link fragments are fetched at idle on fast connections, and only when the page shows no more than twice as many; 0 keeps HTML to intent only.
+	// At most this many visible-link fragments are fetched at idle on fast connections, in document order; 0 keeps HTML to intent only.
 	readonly idleFragments: number;
 	readonly idleWithoutConnectionInfo: boolean;
 	// false: nothing is fetched before a click.
@@ -64,9 +71,11 @@ export type FragmentNavigationState = {
 	readonly prefetch: (url: URL) => void;
 	readonly parse: (url: string, text: string) => FragmentFetched;
 	readonly idleDownloads: boolean;
-	// Schedules the idle tier: at idle, download the landing code and a few fragments of the page links in view.
+	// Schedules the idle tier: at idle, fetch a few page fragments of the links in view; their code waits for intent.
 	readonly rescan: () => void;
 	readonly scrolled: Set<Element>;
+	// Code the intent started preloading, by absolute href, settling once each file has arrived.
+	readonly arriving: Map<string, Promise<unknown>>;
 };
 
 export type FragmentScroll =
@@ -167,12 +176,15 @@ function regionOf(state: FragmentNavigationState, doc: Document): Element | null
 		(
 			doc.querySelector(`script[type="${state.config.routeScriptType}"]`) ??
 			doc.querySelector('script[data-markless-router-link-resumer]')
-		)?.closest('[data-async-container]') ?? null
+		)?.closest(`[${state.config.containerAttributes[0]}]`) ?? null
 	);
 }
 
 function retire(state: FragmentNavigationState, root: Element): void {
-	for (const container of [root, ...root.querySelectorAll('[data-async-container]')]) {
+	for (const container of [
+		root,
+		...root.querySelectorAll(`[${state.config.containerAttributes[0]}]`),
+	]) {
 		const retireContainer = (container as unknown as Record<string, unknown>)[
 			state.config.retireProperty
 		];
@@ -191,13 +203,157 @@ function reportAsync(error: unknown): void {
 	});
 }
 
-function execute(d: Document, script: HTMLScriptElement): void {
-	const type = script.type;
-	if (type && type !== 'module' && type !== 'text/javascript') return;
+// The JavaScript MIME types of the HTML spec, which a browser runs as classic scripts.
+const JAVASCRIPT_TYPE =
+	/^(?:|(?:text|application)\/(?:x-)?(?:java|ecma)script|text\/(?:javascript1\.[0-5]|jscript|livescript))$/;
+
+function scriptKind(script: HTMLScriptElement): 'classic' | 'module' | undefined {
+	const type = script.getAttribute('type');
+	const language = script.getAttribute('language');
+	const essence = (type ?? (language ? `text/${language}` : ''))
+		.split(';')[0]!
+		.trim()
+		.toLowerCase();
+	if (essence === 'module') return 'module';
+	if (!JAVASCRIPT_TYPE.test(essence) || script.hasAttribute('nomodule')) return undefined;
+	return 'classic';
+}
+
+// A parsed or adopted script never runs; a fresh element with its attributes and text does.
+function runnable(d: Document, script: HTMLScriptElement): HTMLScriptElement {
 	const clone = d.createElement('script');
 	for (const attribute of script.attributes) clone.setAttribute(attribute.name, attribute.value);
 	clone.textContent = script.textContent;
-	script.replaceWith(clone);
+	return clone;
+}
+
+const settles = (script: HTMLScriptElement) =>
+	new Promise<unknown>((done) => {
+		script.addEventListener('load', done, { once: true });
+		script.addEventListener('error', done, { once: true });
+	});
+
+// External files this document already ran: a page that includes one again keeps the loaded copy.
+const ranFiles = new WeakMap<Document, Set<string>>();
+
+function filesRan(d: Document): Set<string> {
+	let files = ranFiles.get(d);
+	if (!files) ranFiles.set(d, (files = new Set()));
+	for (const script of d.scripts) if (script.src && scriptKind(script)) files.add(script.src);
+	return files;
+}
+
+type LoadListener = {
+	readonly target: EventTarget;
+	readonly type: string;
+	readonly listener: EventListenerOrEventListenerObject;
+};
+
+// The document fired DOMContentLoaded and load already: listeners the page's scripts add are called once those scripts ran.
+function captureLoadListeners(d: Document, w: Window, into: LoadListener[]): () => void {
+	const targets: Array<readonly [EventTarget, string]> = [];
+	if (d.readyState !== 'loading') targets.push([d, 'DOMContentLoaded']);
+	if (d.readyState === 'complete') targets.push([w, 'load']);
+	const restores = targets.map(([target, type]) => {
+		const own = Object.getOwnPropertyDescriptor(target, 'addEventListener');
+		const add = target.addEventListener;
+		target.addEventListener = function (
+			this: EventTarget,
+			kind: string,
+			listener: EventListenerOrEventListenerObject | null,
+			options?: boolean | AddEventListenerOptions,
+		) {
+			if (kind === type && listener && this === target) into.push({ target, type, listener });
+			return add.call(this, kind, listener, options);
+		};
+		return () => {
+			if (own) Object.defineProperty(target, 'addEventListener', own);
+			else delete (target as { addEventListener?: unknown }).addEventListener;
+		};
+	});
+	return () => {
+		for (const restore of restores) restore();
+	};
+}
+
+function callLoadListeners(listeners: readonly LoadListener[], type: string): void {
+	const event = new Event(type);
+	for (const entry of listeners) {
+		if (entry.type !== type) continue;
+		try {
+			if (typeof entry.listener === 'function') entry.listener.call(entry.target, event);
+			else entry.listener.handleEvent(event);
+		} catch (error) {
+			reportAsync(error);
+		}
+	}
+}
+
+// A landing's order: blocking classic scripts one by one, async as they arrive, then deferred and module scripts, then load listeners.
+async function runScripts(
+	d: Document,
+	scripts: readonly HTMLScriptElement[],
+	ran: Set<string>,
+	current: () => boolean,
+): Promise<void> {
+	const w = d.defaultView!;
+	const listeners: LoadListener[] = [];
+	const release = captureLoadListeners(d, w, listeners);
+	try {
+		const deferred: HTMLScriptElement[] = [];
+		for (const script of scripts) {
+			const kind = scriptKind(script);
+			if (!kind || !script.isConnected) continue;
+			const src = script.hasAttribute('src') ? script.src : '';
+			if (src && ran.has(src)) continue;
+			if (src) ran.add(src);
+			const async = script.hasAttribute('async') && (src !== '' || kind === 'module');
+			if (!async && (kind === 'module' || (src && script.hasAttribute('defer')))) {
+				deferred.push(script);
+				continue;
+			}
+			const clone = runnable(d, script);
+			if (async || !src) {
+				script.replaceWith(clone);
+				continue;
+			}
+			clone.async = false;
+			const done = settles(clone);
+			script.replaceWith(clone);
+			await done;
+			if (!current()) return;
+		}
+		let last: Promise<unknown> | undefined;
+		let tail: HTMLScriptElement | undefined;
+		for (const script of deferred) {
+			if (!script.isConnected) continue;
+			const clone = runnable(d, script);
+			clone.async = false;
+			last = clone.src ? settles(clone) : undefined;
+			tail = clone;
+			script.replaceWith(clone);
+		}
+		// An inline module fires no load event, so a marker queued after the last one says when it ran.
+		if (tail && !last) {
+			const key = `__marklessScriptsRan${Math.random().toString(36).slice(2)}`;
+			const host = w as unknown as Record<string, unknown>;
+			last = new Promise((done) => (host[key] = done));
+			const marker = d.createElement('script');
+			marker.type = 'module';
+			marker.async = false;
+			if (tail.nonce) marker.nonce = tail.nonce;
+			marker.textContent = `window.${key}();`;
+			d.head.append(marker);
+			await last;
+			delete host[key];
+			marker.remove();
+		} else await last;
+		if (!current()) return;
+		callLoadListeners(listeners, 'DOMContentLoaded');
+		callLoadListeners(listeners, 'load');
+	} finally {
+		release();
+	}
 }
 
 function loaded(w: Window, links: readonly HTMLLinkElement[]): Promise<unknown> {
@@ -235,9 +391,8 @@ async function mergeHead(d: Document, next: Document) {
 			else d.head.prepend(node);
 			if (node.localName === 'link' && (node as HTMLLinkElement).rel === 'stylesheet')
 				stylesheets.push(node as HTMLLinkElement);
-			// A kept inline script already ran on this document; only one the destination adds runs.
-			if (node.localName === 'script' && !(node as HTMLScriptElement).src)
-				scripts.push(node as HTMLScriptElement);
+			// A kept head script already ran on this document; only one the destination adds runs.
+			if (node.localName === 'script') scripts.push(node as HTMLScriptElement);
 		}
 		cursor = node;
 	}
@@ -255,10 +410,13 @@ async function mergeHead(d: Document, next: Document) {
 // Only attributes a server document set are the server's to remove: scripts own the rest (a theme class).
 const serverHtmlAttributes = new WeakMap<Document, Set<string>>();
 
-function syncHtmlAttributes(d: Document, next: Document): void {
+function syncHtmlAttributes(d: Document, next: Document, servedProperty: string): void {
 	const root = d.documentElement;
 	const incoming = next.documentElement;
-	for (const name of serverHtmlAttributes.get(d) ?? [])
+	const served =
+		serverHtmlAttributes.get(d) ??
+		((root as unknown as Record<string, readonly string[] | undefined>)[servedProperty] || []);
+	for (const name of served)
 		if (!incoming.hasAttribute(name)) root.removeAttribute(name);
 	for (const attribute of incoming.attributes)
 		if (root.getAttribute(attribute.name) !== attribute.value)
@@ -266,12 +424,62 @@ function syncHtmlAttributes(d: Document, next: Document): void {
 	serverHtmlAttributes.set(d, new Set(incoming.getAttributeNames()));
 }
 
+// Set from the page's config at the start of every swap.
+let containerAttribute = '';
+
 const isContainer = (node: Node): boolean =>
-	node.nodeType === 1 && (node as Element).hasAttribute('data-async-container');
+	node.nodeType === 1 && (node as Element).hasAttribute(containerAttribute);
+
+function pageEnd(host: Node, data: string): Comment | undefined {
+	for (let node = host.lastChild; node; node = node.previousSibling)
+		if (node.nodeType === 8 && (node as Comment).data === data) return node as Comment;
+	return undefined;
+}
+
+function pageStart(host: Node, data: string): Comment | undefined {
+	for (let node = host.firstChild; node; node = node.nextSibling)
+		if (node.nodeType === 8 && (node as Comment).data === data) return node as Comment;
+	return undefined;
+}
+
+function nodesBefore(d: Document, node: Node): DocumentFragment {
+	const nodes = d.createDocumentFragment();
+	while (node.previousSibling) nodes.prepend(node.previousSibling);
+	return nodes;
+}
+
+function nodesAfter(d: Document, node: Node): DocumentFragment {
+	const nodes = d.createDocumentFragment();
+	while (node.nextSibling) nodes.append(node.nextSibling);
+	return nodes;
+}
+
+const scriptsIn = (element: Element): Element[] =>
+	element.localName === 'script' ? [element] : [...element.querySelectorAll('script')];
+
+const serverHostAttributes = new WeakMap<Document, Set<string>>();
+
+// The incoming container is a fresh element; attributes a script set on the outgoing one stay.
+function carryHostAttributes(
+	d: Document,
+	from: Element,
+	to: Element,
+	own: readonly string[],
+): void {
+	const server = serverHostAttributes.get(d);
+	serverHostAttributes.set(d, new Set(to.getAttributeNames()));
+	for (const attribute of from.attributes)
+		if (
+			!to.hasAttribute(attribute.name) &&
+			!server?.has(attribute.name) &&
+			!own.includes(attribute.name)
+		)
+			to.setAttribute(attribute.name, attribute.value);
+}
 
 // A document app's shell has no runtime, so it is morphed in place: unchanged chrome keeps its nodes.
 // Containers are always replaced whole: their DOM is the new page's resume payload's to locate.
-function morphChildren(d: Document, from: Element, to: Element, fresh: Element[]): void {
+function morphChildren(d: Document, from: Node, to: Node, fresh: Element[]): void {
 	let cursor = from.firstChild;
 	const skipContainers = () => {
 		while (cursor && isContainer(cursor)) {
@@ -409,7 +617,7 @@ async function streamAppends(
 		}
 	}
 	flush(true);
-	end.parentNode?.removeChild(end);
+	if ((end as Comment).data !== state.config.pageEndComment) end.parentNode?.removeChild(end);
 	return signal.aborted ? undefined : all;
 }
 
@@ -422,6 +630,7 @@ export async function navigate(
 	const state = (d as FragmentHost).__marklessFragmentNav;
 	const w = d.defaultView;
 	if (!state || !w) return;
+	containerAttribute = state.config.containerAttributes[0];
 	const session = sessionFor(d);
 	const id = ++session.navigation;
 	session.streaming?.abort();
@@ -442,12 +651,24 @@ export async function navigate(
 	const documentLoads = state.config.documentLoads;
 	const incoming = documentLoads ? next.body : regionOf(state, next);
 	const outgoing = documentLoads ? d.body : regionOf(state, d);
-	const scope = documentLoads ? d.body : outgoing?.parentElement;
+	const scope = documentLoads && !isContainer(d.body) ? d.body : outgoing?.parentElement;
 	if (!incoming || !outgoing || !scope) {
 		fallback(fetched.url);
 		return;
 	}
+	// The destination shows once its own code has arrived, so its first interaction never waits on a fetch.
+	const code = [...next.head.querySelectorAll<HTMLLinkElement>('link[rel="modulepreload"]')].map(
+		(link) => state.arriving.get(new URL(link.getAttribute('href') ?? '', d.baseURI).href),
+	);
+	for (const item of state.routes[url.pathname] ?? [])
+		code.push(
+			state.arriving.get(
+				new URL(typeof item === 'string' ? item : item.href, d.baseURI).href,
+			),
+		);
+	const ranFiles = filesRan(d);
 	const head = await mergeHead(d, next);
+	await Promise.race([Promise.all(code), new Promise((resolve) => w.setTimeout(resolve, 3000))]);
 	if (id !== session.navigation) return taken.abort();
 	let restore = scroll;
 	if (mode === 'traverse') {
@@ -485,31 +706,67 @@ export async function navigate(
 	(w as unknown as Record<string, unknown>)[state.config.streamExecutorGlobal] = undefined;
 	for (const element of d.querySelectorAll(state.config.streamedArmSelector)) element.remove();
 	state.shown = pageKey(new URL(w.location.href));
-	if (documentLoads) syncHtmlAttributes(d, next);
-	const fresh: Element[] = [];
+	if (documentLoads) syncHtmlAttributes(d, next, state.config.servedHtmlAttributesProperty);
 	let region: Element;
-	if (documentLoads) {
+	let end: Comment;
+	let scripts: Element[];
+	if (documentLoads && !isContainer(d.body)) {
+		const fresh: Element[] = [];
 		region = d.body;
 		morphChildren(d, region, incoming, fresh);
+		scripts = fresh.flatMap(scriptsIn);
+		region.append((end = d.createComment('')));
 	} else {
 		region = d.adoptNode(incoming);
-		outgoing.replaceWith(region);
-		fresh.push(region);
+		const leavingEnd = pageEnd(outgoing, state.config.pageEndComment);
+		if (leavingEnd) {
+			carryHostAttributes(d, outgoing, region, state.config.containerAttributes);
+			end =
+				pageEnd(region, state.config.pageEndComment) ??
+				region.appendChild(d.createComment(state.config.pageEndComment));
+			// The document's own nodes after the page stay; a document app morphs them to its next shell.
+			const focused = d.activeElement as HTMLElement | null;
+			const kept = nodesAfter(d, leavingEnd);
+			const arriving = nodesAfter(d, end);
+			const fresh: Element[] = [];
+			if (documentLoads) morphChildren(d, kept, arriving, fresh);
+			const leavingStart = pageStart(outgoing, state.config.pageStartComment);
+			let start = pageStart(region, state.config.pageStartComment);
+			if (leavingStart || start) {
+				start ??= region.insertBefore(
+					d.createComment(state.config.pageStartComment),
+					region.firstChild,
+				);
+				const keptBefore = leavingStart
+					? nodesBefore(d, leavingStart)
+					: d.createDocumentFragment();
+				const arrivingBefore = nodesBefore(d, start);
+				if (documentLoads) morphChildren(d, keptBefore, arrivingBefore, fresh);
+				region.insertBefore(keptBefore, start);
+			}
+			scripts = [...scriptsIn(region), ...fresh.flatMap(scriptsIn)];
+			region.append(kept);
+			outgoing.replaceWith(region);
+			// The document's own nodes moved to the new element; focus inside them stays put.
+			if (focused && focused !== d.activeElement && region.contains(focused))
+				focused.focus({ preventScroll: true });
+		} else {
+			scripts = scriptsIn(region);
+			outgoing.replaceWith(region);
+			region.after((end = d.createComment('')));
+		}
 	}
 	// 'instant': a `scroll-behavior: smooth` page would otherwise animate every landing.
 	for (const box of offsets)
 		sameBox(scope, box)?.scrollTo({ top: box.top, left: box.left, behavior: 'instant' });
-	const end = d.createComment('');
-	if (documentLoads) region.append(end);
-	else region.after(end);
 	for (const element of head.stale) element.remove();
 	if (next.title && d.title !== next.title) d.title = next.title;
-	for (const script of head.scripts) execute(d, script);
-	for (const element of fresh)
-		for (const script of element.localName === 'script'
-			? [element]
-			: element.querySelectorAll('script'))
-			execute(d, script as HTMLScriptElement);
+	const ran = runScripts(
+		d,
+		[...head.scripts, ...(scripts as HTMLScriptElement[])],
+		ranFiles,
+		() => id === session.navigation,
+	);
 	const active = d.activeElement as HTMLElement | null;
 	if (active && active !== d.body && !region.contains(active)) active.blur?.();
 	(region.querySelector('[autofocus]') as HTMLElement | null)?.focus();
@@ -540,4 +797,5 @@ export async function navigate(
 		if (w.requestIdleCallback) w.requestIdleCallback(idle, { timeout: 2000 });
 		else w.setTimeout(idle, 200);
 	}, reportAsync);
+	await ran;
 }