@lovrozagar/flare 0.1.0

package/src/navigation/types.ts

@@ -0,0 +1,59 @@
+import type { JSX } from "solid-js";
+import type {
+	ClientErrorRenderProps,
+	ClientNotFoundRenderProps,
+	ClientUnauthenticatedRenderProps,
+	ClientUnauthorizedRenderProps,
+	RenderProps,
+} from "../outlet/types.ts";
+import type { SearchParams } from "../url/index.ts";
+
+export interface LocationSnapshot {
+	hash: string;
+	params: Record<string, string | string[]>;
+	pathname: string;
+	search: SearchParams;
+}
+
+export interface EffectsConfig {
+	loaderDeps?: (ctx: { search: SearchParams }) => unknown[];
+	shouldRefetch?: (ctx: {
+		location: { current: LocationSnapshot; next: LocationSnapshot };
+		trigger: string;
+	}) => boolean;
+}
+
+export interface LoadedRouteModule {
+	_type: "layout" | "render" | "root-layout";
+	effectsConfig?: EffectsConfig;
+	errorRender?: (props: ClientErrorRenderProps) => JSX.Element;
+	notFoundRender?: (props: ClientNotFoundRenderProps) => JSX.Element;
+	cache?: {
+		client?:
+			| {
+					cacheDeferred?: boolean;
+					gcTime?: number;
+					prefetchGcTime?: number;
+					prefetchStaleTime?: number;
+					staleTime?: number;
+			  }
+			| false;
+	};
+	render: (props: RenderProps) => JSX.Element;
+	unauthenticatedRender?: (props: ClientUnauthenticatedRenderProps) => JSX.Element;
+	unauthorizedRender?: (props: ClientUnauthorizedRenderProps) => JSX.Element;
+	variablePath: string;
+	virtualPath: string;
+}
+
+export interface LoadedRouteModules {
+	layouts: LoadedRouteModule[];
+	page: LoadedRouteModule;
+	params: Record<string, string | string[]>;
+}
+
+export type LoadRouteModulesFn = (
+	pathname: string,
+	routeTree: unknown,
+	layouts: Record<string, () => Promise<{ default: unknown }>>,
+) => Promise<LoadedRouteModules>;

package/src/navigation-progress/index.tsx

@@ -0,0 +1,247 @@
+import { createEffect, type JSX, onCleanup, useContext } from "solid-js";
+import { isServer } from "solid-js/web";
+import { RouterContext } from "../outlet/index.tsx";
+
+export interface NavigationProgressProps {
+	color?: string;
+	height?: number;
+	minDisplayTime?: number;
+	showPeg?: boolean;
+	speed?: number;
+	trickleSpeed?: number;
+	zIndex?: number;
+}
+
+function clamp(n: number, min: number, max: number): number {
+	if (n < min) return min;
+	if (n > max) return max;
+	return n;
+}
+
+/**
+ * nprogress-style increment curve.
+ * Slows dramatically as it approaches 1 to feel realistic.
+ */
+function trickleIncrement(current: number): number {
+	if (current < 0.2) return 0.1;
+	if (current < 0.5) return 0.04;
+	if (current < 0.8) return 0.02;
+	if (current < 0.99) return 0.005;
+	return 0;
+}
+
+/**
+ * Convert 0..1 progress to translate3d percentage (-100%..0%).
+ * GPU-composited — no layout/paint, just composite.
+ */
+function toBarPerc(n: number): number {
+	return (-1 + n) * 100;
+}
+
+function toTranslate(n: number): string {
+	return `translate3d(${toBarPerc(n)}%,0,0)`;
+}
+
+export function NavigationProgress(props: NavigationProgressProps): JSX.Element {
+	let wrapperRef: HTMLDivElement | undefined;
+	let barRef: HTMLDivElement | undefined;
+	let pegRef: HTMLDivElement | undefined;
+
+	const speed = (): number => props.speed ?? 200;
+	const trickleSpeed = (): number => props.trickleSpeed ?? 200;
+	const showPeg = (): boolean => props.showPeg !== false;
+
+	let status: number | null = null;
+	let trickleTimer: ReturnType<typeof setTimeout> | undefined;
+	let fadeTimer: ReturnType<typeof setTimeout> | undefined;
+	let minDisplayTimer: ReturnType<typeof setTimeout> | undefined;
+	let startTime = 0;
+	let pendingComplete = false;
+
+	function clearTimers(): void {
+		if (trickleTimer !== undefined) {
+			clearTimeout(trickleTimer);
+			trickleTimer = undefined;
+		}
+		if (fadeTimer !== undefined) {
+			clearTimeout(fadeTimer);
+			fadeTimer = undefined;
+		}
+		if (minDisplayTimer !== undefined) {
+			clearTimeout(minDisplayTimer);
+			minDisplayTimer = undefined;
+		}
+	}
+
+	function set(value: number): void {
+		const started = status !== null;
+		const n = clamp(value, 0.08, 1);
+		status = n === 1 ? null : n;
+
+		if (!barRef || !wrapperRef) return;
+
+		/* Force reflow before transition on first render */
+		if (!started) void wrapperRef.offsetWidth;
+
+		barRef.style.transition = `all ${speed()}ms linear`;
+		barRef.style.transform = toTranslate(n);
+		barRef.setAttribute("aria-valuenow", String(Math.round(n * 100)));
+
+		if (pegRef) {
+			pegRef.style.display = showPeg() ? "block" : "none";
+		}
+
+		if (n === 1) {
+			/*
+			 * nprogress completion sequence:
+			 * 1. Snap wrapper to opacity 1, no transition
+			 * 2. Reflow
+			 * 3. After speed ms: fade wrapper to opacity 0
+			 * 4. After speed ms: reset bar position
+			 */
+			wrapperRef.style.transition = "none";
+			wrapperRef.style.opacity = "1";
+			void wrapperRef.offsetWidth;
+
+			fadeTimer = setTimeout(() => {
+				if (!wrapperRef || !barRef) return;
+				wrapperRef.style.transition = `all ${speed()}ms linear`;
+				wrapperRef.style.opacity = "0";
+				fadeTimer = setTimeout(() => {
+					if (!wrapperRef || !barRef) return;
+					barRef.style.transition = "none";
+					barRef.style.transform = toTranslate(0);
+					wrapperRef.style.transition = "none";
+					wrapperRef.style.opacity = "1";
+				}, speed());
+			}, speed());
+		} else {
+			wrapperRef.style.opacity = "1";
+		}
+	}
+
+	function inc(amount?: number): void {
+		const n = status;
+		if (n === null) {
+			start();
+			return;
+		}
+		if (n > 1) return;
+
+		const increment = amount ?? trickleIncrement(n);
+		set(clamp(n + increment, 0, 0.994));
+	}
+
+	function start(): void {
+		if (status === null) set(0);
+		startTime = Date.now();
+		pendingComplete = false;
+
+		function work(): void {
+			trickleTimer = setTimeout(() => {
+				if (status === null) return;
+				inc();
+				work();
+			}, trickleSpeed());
+		}
+		work();
+	}
+
+	function done(): void {
+		/* nprogress-style: burst forward with random increment before completing */
+		inc(0.3 + 0.5 * Math.random());
+		set(1);
+	}
+
+	function completeBar(): void {
+		clearTimers();
+		pendingComplete = false;
+		done();
+	}
+
+	function handleComplete(): void {
+		const minTime = props.minDisplayTime ?? 0;
+		const elapsed = Date.now() - startTime;
+
+		if (elapsed < minTime) {
+			pendingComplete = true;
+			minDisplayTimer = setTimeout(() => {
+				if (pendingComplete) {
+					completeBar();
+				}
+			}, minTime - elapsed);
+		} else {
+			completeBar();
+		}
+	}
+
+	/* SSR: effects are no-ops. Client: RouterContext available via full-document hydration. */
+	const ctx = useContext(RouterContext);
+
+	if (!isServer && ctx) {
+		createEffect(() => {
+			const phase = ctx.navigationPhase();
+
+			if (phase === "loading") {
+				clearTimers();
+				start();
+			} else if (phase === "idle" && status !== null) {
+				handleComplete();
+			} else if (phase === "transitioning" && status !== null) {
+				handleComplete();
+			}
+		});
+
+		onCleanup(clearTimers);
+	}
+
+	const barColor = (): string => props.color ?? "currentColor";
+
+	return (
+		<div
+			ref={wrapperRef}
+			style={{
+				height: `${props.height ?? 2}px`,
+				left: "0",
+				"pointer-events": "none",
+				position: "fixed",
+				top: "0",
+				width: "100%",
+				"z-index": props.zIndex ?? 9999,
+			}}
+		>
+			<div
+				aria-label="Page load progress"
+				aria-valuemax="100"
+				aria-valuemin="0"
+				aria-valuenow={0}
+				ref={barRef}
+				role="progressbar"
+				style={{
+					"background-color": barColor(),
+					height: "100%",
+					left: "0",
+					position: "absolute",
+					top: "0",
+					transform: toTranslate(0),
+					transition: "all 0 linear",
+					width: "100%",
+				}}
+			>
+				<div
+					ref={pegRef}
+					style={{
+						"box-shadow": `0 0 10px ${barColor()}, 0 0 5px ${barColor()}`,
+						display: showPeg() ? "block" : "none",
+						height: "100%",
+						opacity: "1",
+						position: "absolute",
+						right: "0",
+						transform: "rotate(3deg) translate(0px, -4px)",
+						width: "100px",
+					}}
+				/>
+			</div>
+		</div>
+	) as JSX.Element;
+}

package/src/navigation-progress.ts

@@ -0,0 +1 @@
+export { NavigationProgress, type NavigationProgressProps } from "./navigation-progress/index.tsx";

package/src/ndjson-client/index.ts

@@ -0,0 +1,376 @@
+import { NotFoundError, RedirectResponse, UnauthenticatedError, UnauthorizedError } from "../errors/index.ts";
+import { warn } from "../logger.ts";
+import type { HeadConfig } from "../route-builder/types.ts";
+import type { DeferredResolver } from "../state-parser/index.ts";
+import { hydrateLoaderData } from "../state-parser/index.ts";
+
+const MAX_LINE_BYTES = 5 * 1024 * 1024;
+const MAX_MESSAGES = 10_000;
+
+export interface NDJSONFetchOptions {
+	matchIds?: string[];
+	prefetch?: boolean;
+	queryClient?: unknown;
+	signal?: AbortSignal;
+	url: string;
+}
+
+export interface NDJSONFetchResult {
+	matches: FetchedMatch[];
+	perRouteHeads: PerRouteHead[];
+	success: boolean;
+}
+
+export interface FetchedMatch {
+	error?: Error;
+	hasDeferredMarkers?: boolean;
+	loaderData: unknown;
+	matchId: string;
+	preloaderContext?: Record<string, unknown>;
+}
+
+export interface PerRouteHead {
+	head: HeadConfig;
+	matchId: string;
+}
+
+interface NDJSONMessage {
+	a?: unknown[];
+	d?: unknown;
+	e?: { message: string; name?: string };
+	k?: string;
+	l?: string;
+	m?: string;
+	p?: Record<string, unknown>;
+	/* Redirect fields (t:"x") */
+	r?: boolean;
+	s?: number;
+	t: string;
+	u?: string;
+	xl?: boolean;
+}
+
+/*
+ * Reconstruct the correct error class from NDJSON error name.
+ * Server sends `{ message, name }` — client needs `instanceof` checks
+ * for NotFoundError, UnauthenticatedError, UnauthorizedError.
+ */
+function reconstructError(e?: { message: string; name?: string }): Error {
+	const message = e?.message ?? "Unknown error";
+	switch (e?.name) {
+		case "NotFoundError":
+			return new NotFoundError(message);
+		case "UnauthenticatedError":
+			return new UnauthenticatedError(message);
+		case "UnauthorizedError":
+			return new UnauthorizedError(message);
+		default: {
+			const err = new Error(message);
+			if (e?.name) err.name = e.name;
+			return err;
+		}
+	}
+}
+
+const SERVER_LOG_PREFIX = "%c[server]";
+const SERVER_LOG_STYLE = "color:#60a5fa;font-weight:bold";
+const SOURCE_STYLE = "color:#9ca3af";
+
+function forwardServerLog(msg: NDJSONMessage): void {
+	const args = Array.isArray(msg.a) ? msg.a : [];
+	const prefix = msg.s
+		? [SERVER_LOG_PREFIX, SERVER_LOG_STYLE, `%c ${msg.s}`, SOURCE_STYLE, ...args]
+		: [SERVER_LOG_PREFIX, SERVER_LOG_STYLE, ...args];
+	switch (msg.l) {
+		case "warn":
+			console.warn(...prefix);
+			break;
+		case "error":
+			console.error(...prefix);
+			break;
+		default:
+			console.log(...prefix);
+			break;
+	}
+}
+
+export async function fetchNDJSON(options: NDJSONFetchOptions): Promise<NDJSONFetchResult> {
+	const headers: Record<string, string> = { "x-d": "1" };
+
+	if (options.matchIds) {
+		headers["x-m"] = options.matchIds.join(",");
+	}
+
+	if (options.prefetch) {
+		headers["x-p"] = "1";
+	}
+
+	const response = await fetch(options.url, {
+		headers,
+		signal: options.signal,
+	});
+
+	const contentType = response.headers?.get("content-type") ?? "";
+	const isNdjson = contentType.includes("ndjson");
+	/* Loader errors often travel as HTTP 500 + application/x-ndjson. Dropping the
+	 * body makes retry() rebuild matches from a cache that never stored the
+	 * pipeline error, so the error UI cannot recover. */
+	if (!response.ok && !isNdjson) {
+		return { matches: [], perRouteHeads: [], success: false };
+	}
+
+	const matches: FetchedMatch[] = [];
+	const perRouteHeads: PerRouteHead[] = [];
+	const deferredResolvers = new Map<string, DeferredResolver>();
+
+	let loadersReadyResolve: () => void = () => {};
+	let loadersReadyResolved = false;
+	const loadersReady = new Promise<void>((resolve) => {
+		loadersReadyResolve = resolve;
+	});
+
+	function resolveLoadersReady() {
+		if (!loadersReadyResolved) {
+			loadersReadyResolved = true;
+			loadersReadyResolve();
+		}
+	}
+
+	if (!response.body) {
+		return { matches: [], perRouteHeads: [], success: false };
+	}
+
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+
+	function processLine(raw: string) {
+		const trimmed = raw.trim();
+		if (!trimmed) return;
+
+		let msg: NDJSONMessage;
+		try {
+			const parsed: unknown = JSON.parse(trimmed);
+			if (typeof parsed !== "object" || parsed === null || typeof (parsed as NDJSONMessage).t !== "string") {
+				warn("ndjson", "invalid message, skipping", trimmed);
+				return;
+			}
+			msg = parsed as NDJSONMessage;
+		} catch (e: unknown) {
+			warn("ndjson", "invalid message, skipping", e);
+			return;
+		}
+
+		switch (msg.t) {
+			case "g": {
+				forwardServerLog(msg);
+				break;
+			}
+
+			case "l": {
+				if (options.prefetch) {
+					matches.push({
+						hasDeferredMarkers: containsDeferredMarkers(msg.d) || undefined,
+						loaderData: msg.d,
+						matchId: msg.m ?? "",
+						preloaderContext: msg.p,
+					});
+				} else {
+					const sizeBefore = deferredResolvers.size;
+					const hydrated = hydrateLoaderData(msg.m ?? "", msg.d, deferredResolvers);
+					matches.push({
+						hasDeferredMarkers: deferredResolvers.size > sizeBefore || undefined,
+						loaderData: hydrated,
+						matchId: msg.m ?? "",
+						preloaderContext: msg.p,
+					});
+				}
+				break;
+			}
+
+			case "c": {
+				const resolverKey = `${msg.m}:${msg.k}`;
+				const resolver = deferredResolvers.get(resolverKey);
+				if (resolver) {
+					resolver.resolve(msg.d);
+					deferredResolvers.delete(resolverKey);
+				}
+				break;
+			}
+
+			case "e": {
+				const err = reconstructError(msg.e);
+				if (msg.k) {
+					const resolverKey = `${msg.m}:${msg.k}`;
+					const resolver = deferredResolvers.get(resolverKey);
+					if (resolver) {
+						resolver.reject(err);
+						deferredResolvers.delete(resolverKey);
+					}
+				} else {
+					matches.push({
+						error: err,
+						loaderData: undefined,
+						matchId: msg.m ?? "",
+					});
+				}
+				break;
+			}
+
+			case "h": {
+				if (typeof msg.d === "object" && msg.d !== null) {
+					perRouteHeads.push({
+						head: msg.d as HeadConfig,
+						matchId: msg.m ?? "",
+					});
+				}
+				break;
+			}
+
+			case "x": {
+				reader.cancel();
+				rejectPendingResolvers();
+				if (msg.xl) {
+					throw new RedirectResponse({
+						href: msg.u ?? "/",
+						replace: msg.r,
+						status: msg.s,
+					});
+				}
+				throw new RedirectResponse({
+					replace: msg.r,
+					status: msg.s,
+					to: msg.u ?? "/",
+				});
+			}
+
+			case "q": {
+				if (options.queryClient && Array.isArray(msg.d)) {
+					import("../query-client")
+						.then(({ hydrateQueryCache }) => {
+							hydrateQueryCache(
+								options.queryClient as Parameters<typeof hydrateQueryCache>[0],
+								msg.d as Parameters<typeof hydrateQueryCache>[1],
+							);
+						})
+						.catch(() => {});
+				}
+				break;
+			}
+
+			case "r": {
+				resolveLoadersReady();
+				break;
+			}
+
+			case "d": {
+				resolveLoadersReady();
+				break;
+			}
+
+			default:
+				break;
+		}
+	}
+
+	function rejectPendingResolvers() {
+		for (const [key, resolver] of deferredResolvers) {
+			resolver.reject(new Error("Navigation cancelled"));
+			deferredResolvers.delete(key);
+		}
+	}
+
+	const readPromise = (async () => {
+		let messageCount = 0;
+		try {
+			while (true) {
+				if (options.signal?.aborted) {
+					reader.cancel();
+					rejectPendingResolvers();
+					break;
+				}
+
+				const { done, value } = await reader.read();
+				if (done) {
+					/* Flush any buffered partial UTF-8 bytes from the decoder */
+					buffer += decoder.decode();
+					if (buffer.trim()) {
+						processLine(buffer);
+					}
+					resolveLoadersReady();
+					rejectPendingResolvers();
+					break;
+				}
+
+				buffer += decoder.decode(value, { stream: true });
+				if (buffer.length > MAX_LINE_BYTES) {
+					warn("ndjson", "line buffer exceeded maximum size, aborting stream");
+					reader.cancel();
+					rejectPendingResolvers();
+					resolveLoadersReady();
+					break;
+				}
+				const lines = buffer.split("\n");
+				buffer = lines.pop() ?? "";
+
+				for (const ln of lines) {
+					messageCount++;
+					if (messageCount > MAX_MESSAGES) {
+						warn("ndjson", "max message count exceeded, aborting stream");
+						reader.cancel();
+						rejectPendingResolvers();
+						resolveLoadersReady();
+						return;
+					}
+					processLine(ln);
+				}
+			}
+		} catch (e) {
+			rejectPendingResolvers();
+			/* Redirects always propagate — caller must handle redirect even mid-stream */
+			if (e instanceof RedirectResponse) {
+				throw e;
+			}
+			if (loadersReadyResolved) {
+				warn("ndjson", "post-loaders stream error", e);
+				return;
+			}
+			/* Error before loaders ready — propagate so caller sees the failure */
+			throw e;
+		} finally {
+			if (typeof reader.releaseLock === "function") reader.releaseLock();
+		}
+	})();
+
+	/*
+	 * Track redirects that arrive after loadersReady resolves.
+	 * Non-redirect errors are swallowed — they happen after loaders
+	 * are already delivered, so the caller doesn't need them.
+	 */
+	let pendingRedirect: RedirectResponse | undefined;
+	readPromise.catch((e) => {
+		if (e instanceof RedirectResponse) pendingRedirect = e;
+	});
+
+	/* Wait for loadersReady, but if readPromise rejects first, propagate */
+	await Promise.race([loadersReady, readPromise]);
+
+	/*
+	 * Flush microtask queue so the readPromise catch handler has a chance
+	 * to set pendingRedirect if the redirect arrived in the same chunk.
+	 */
+	await new Promise<void>((r) => queueMicrotask(r));
+	if (pendingRedirect) throw pendingRedirect;
+
+	return { matches, perRouteHeads, success: true };
+}
+
+const MAX_DEFERRED_DEPTH = 50;
+
+function containsDeferredMarkers(data: unknown, depth = 0): boolean {
+	if (depth > MAX_DEFERRED_DEPTH) return false;
+	if (data === null || data === undefined || typeof data !== "object") return false;
+	if ((data as Record<string, unknown>).__deferred === true) return true;
+	if (Array.isArray(data)) return data.some((v) => containsDeferredMarkers(v, depth + 1));
+	return Object.values(data as Record<string, unknown>).some((v) => containsDeferredMarkers(v, depth + 1));
+}