@lovrozagar/flare 0.1.1 → 0.2.0

package/src/ssr/index.tsx

@@ -1,9 +1,10 @@
-import type { JSX } from "solid-js";
-import { createComponent, Hydration, renderToStream as solidRenderToStream } from "solid-js/web";
+import { getNextChildId, getOwner } from "solid-js";
+import type { JSX } from "@solidjs/web";
+import { createComponent, Hydration, renderToStream as solidRenderToStream } from "@solidjs/web";
 import type { GlobalBoundaries } from "../boundaries/index.ts";
 import { BroadcastProvider } from "../broadcast/provider.tsx";
 import { createMatchCache, createPrefetchCache } from "../caches/index.ts";
-import { setSSRContext } from "../components/ssr-context.tsx";
+import { SSRContextProvider } from "../components/ssr-context.tsx";
 import type { DeferContext, DeferredEntry } from "../defer/index.ts";
 import { isDeferred } from "../defer/index.ts";
 import { DirectionProvider } from "../direction.ts";
@@ -28,8 +29,10 @@ import type { ServerLogEntry } from "@lovrozagar/flare/server-context";
 import { clearScopedStyles, getScopedStyles, RUNTIME_SHEET_ID } from "../styles/index.ts";
 import { CRITICAL_SHEET_ID, injectCriticalAppend, type SxCssManifest } from "./critical-css.ts";
 import { ThemeProvider } from "../theme.ts";
+import { GLOBAL_DEFER, GLOBAL_QUERIES } from "../protocol.ts";
 import { parseSearchParams, type SearchParams } from "../url/index.ts";
 import { renderHeadToHtml } from "./head.ts";
+import { hoistHydrationHeadMarkers } from "./hoist-head-markers.ts";
 import { buildHeadPrefix } from "./head-prefix.ts";
 
 export { mergeHeadConfigs } from "../internal.ts";
@@ -394,9 +397,19 @@ function RootRenderer(props: {
 	preloaderContext: Record<string, unknown> | undefined;
 	renderFn: (p: RenderProps) => JSX.Element;
 }): JSX.Element {
+	/*
+	 * Client `createContext` children() consumes one hydration id in this
+	 * owner before the layout runs; the server's children() memos do not.
+	 * Advance the server counter so <html> `_hk` matches hydrate.
+	 */
+	const owner = getOwner();
+	if (owner?.id != null) getNextChildId(owner);
 	const router = useRouter();
+	/* Getter so <Outlet> does not consume hydration child ids before <html>. */
 	return props.renderFn({
-		children: <Outlet />,
+		get children() {
+			return <Outlet />;
+		},
 		loaderData: props.data,
 		location: props.location,
 		preloaderContext: props.preloaderContext,
@@ -419,7 +432,7 @@ function buildComponentTree(config: SSRConfig, flareStateScript: string): () =>
 	const matches = config.matches;
 
 	return () => {
-		setSSRContext({
+		const ssrCtxValue = {
 			direction: config.router?.direction,
 			entryScript: config.entryScript,
 			flareStateScript,
@@ -427,7 +440,7 @@ function buildComponentTree(config: SSRConfig, flareStateScript: string): () =>
 			nonce: config.nonce,
 			resolvedHead: config.resolvedHead,
 			theme: config.router?.theme,
-		});
+		};
 
 		const lastMatch = matches[matches.length - 1];
 		const location: ProviderLocation = {
@@ -452,8 +465,8 @@ function buildComponentTree(config: SSRConfig, flareStateScript: string): () =>
 		 * Full-document hydration: providers wrap root layout so components
 		 * inside the root layout (e.g. NavigationProgress) have RouterContext.
 		 *
-		 * SSR:    Hydration > Theme > Direction > FlareProvider > rootRenderFn({children: Outlet})
-		 * Client: Dummy     > Theme > Direction > FlareProvider > rootRenderFn({children: Outlet})
+		 * SSR and client: Hydration > QCP? > SSRContextProvider > Theme >
+		 * Direction > Broadcast > FlareProvider > rootRenderFn({children: Outlet})
 		 *
 		 * All JSX inside the Hydration boundary — no pre-evaluated constants outside.
 		 */
@@ -480,37 +493,39 @@ function buildComponentTree(config: SSRConfig, flareStateScript: string): () =>
 		 * inside the Provider's context scope during Solid SSR.
 		 */
 		const renderInner = () => (
-			<ThemeProvider config={config.router?.theme}>
-				<DirectionProvider config={config.router?.direction}>
-					<BroadcastProvider>
-						<FlareProvider
-							boundaries={rootBoundaries}
-							caseSensitive={config.router?.caseSensitive}
-							initialLocation={location}
-							layouts={config.router?.layouts ?? {}}
-							localeConfig={config.router?.locale}
-							matchCache={matchCache}
-							matches={clientMatches}
-							params={location.params}
-							prefetchCache={prefetchCache}
-							resolvers={new Map()}
-							routeTree={config.router?.routeTree ?? createTreeNode()}
-							search={location.search}
-						>
-							{rootRenderFn ? (
-								<RootRenderer
-									data={rootMatch?.loaderData}
-									location={location}
-									preloaderContext={rootMatch?.preloaderContext}
-									renderFn={rootRenderFn}
-								/>
-							) : (
-								<Outlet />
-							)}
-						</FlareProvider>
-					</BroadcastProvider>
-				</DirectionProvider>
-			</ThemeProvider>
+			<SSRContextProvider value={ssrCtxValue}>
+				<ThemeProvider config={config.router?.theme}>
+					<DirectionProvider config={config.router?.direction}>
+						<BroadcastProvider>
+							<FlareProvider
+								boundaries={rootBoundaries}
+								caseSensitive={config.router?.caseSensitive}
+								initialLocation={location}
+								layouts={config.router?.layouts ?? {}}
+								localeConfig={config.router?.locale}
+								matchCache={matchCache}
+								matches={clientMatches}
+								params={location.params}
+								prefetchCache={prefetchCache}
+								resolvers={new Map()}
+								routeTree={config.router?.routeTree ?? createTreeNode()}
+								search={location.search}
+							>
+								{rootRenderFn ? (
+									RootRenderer({
+										data: rootMatch?.loaderData,
+										location,
+										preloaderContext: rootMatch?.preloaderContext,
+										renderFn: rootRenderFn,
+									})
+								) : (
+									<Outlet />
+								)}
+							</FlareProvider>
+						</BroadcastProvider>
+					</DirectionProvider>
+				</ThemeProvider>
+			</SSRContextProvider>
 		);
 
 		return (
@@ -532,18 +547,15 @@ function buildComponentTree(config: SSRConfig, flareStateScript: string): () =>
  * Inject resolved head tags, CSP nonce meta, and scoped styles before </head>.
  * Returns updated buffer with head content injected, or original buffer if </head> not found.
  *
- * Head structure (order matters for first paint + Chrome's preload scanner):
- *   1. <meta name="csp-nonce"> with nonce attribute (browser hides it from DOM/CSS)
- *   2. viewport (if the app omitted one)
- *   3. theme / direction / locale blocking scripts — before CSS so first land is themed
- *   4. <link rel="modulepreload"> + stylesheets
- *   5. Solid's SSR output (layout ThemeScript is a duplicate, harmless)
- *   6. Resolved <head> tags (title, meta, etc.)
- *   7. Scoped styles
+ * Head structure:
+ *   1. Solid's hydratable head children (`<!--$-->` first — required for Solid 2)
+ *   2. CSP nonce / viewport / theme / direction / locale scripts (headPrefix)
+ *   3. modulepreload + stylesheets
+ *   4. Resolved <head> tags (title, meta, etc.)
+ *   5. Scoped styles
  *
- * Theme scripts must precede stylesheets. Modulepreloads stay after those
- * tiny inline scripts so Chrome can still mark them isLinkPreload when CSP
- * has no 'strict-dynamic' (crbug.com/702612).
+ * Prefix is appended (not prepended) so hydrate can walk Solid's markers.
+ * Theme scripts still run in `<head>` before `<body>` is parsed.
  */
 function injectHeadContent(
 	buffer: string,
@@ -565,11 +577,12 @@ function injectHeadContent(
 
 	let headSuffix = "";
 	const headHtml = renderHeadToHtml(config.resolvedHead, config.nonce);
-	if (headHtml) headSuffix += headHtml;
+	/* Runtime scoped sheet first so route `head().custom.styles` win at equal specificity. */
 	if (scopedStyles) {
 		const safeStyles = scopedStyles.replace(/<\/style\b/gi, "<\\/style");
 		headSuffix += `<style id="${RUNTIME_SHEET_ID}" nonce="${escapedNonce}">${safeStyles}</style>`;
 	}
+	if (headHtml) headSuffix += headHtml;
 	/* Critical-CSS placeholder — body not known yet; late-inject populates it near </body>. */
 	if (config.sxCssManifest) {
 		const nonceAttr = config.nonce ? ` nonce="${escapedNonce}"` : "";
@@ -617,8 +630,8 @@ function injectHeadContent(
 		headSuffix += `<style nonce="${escapedNonce}">body{${cssText}}</style>`;
 	}
 
-	const result = buffer.replace(/<head[^>]*>/, `$&${headPrefix}`);
-	return result.replace("</head>", `${headSuffix}${extraSuffix}</head>`);
+	const result = buffer.replace("</head>", `${headPrefix}${headSuffix}${extraSuffix}</head>`);
+	return hoistHydrationHeadMarkers(result);
 }
 
 /**
@@ -688,7 +701,7 @@ export function renderToStream(config: SSRConfig): SSRResult {
 	const decoder = new TextDecoder();
 
 	/*
-	 * Solid only injects _$HY when async work exists (Suspense, deferred data).
+	 * Solid only injects _$HY when async work exists (Loading, deferred data).
 	 * For sync-only rendering, _$HY is never set, but client `hydrate()` always
 	 * reads `globalThis._$HY.done`. Inject a minimal _$HY init unconditionally.
 	 */
@@ -805,14 +818,6 @@ export function renderToStream(config: SSRConfig): SSRResult {
 
 				/* Stream deferred resolution scripts after HTML */
 				if (config.deferContexts && config.deferContexts.size > 0) {
-					/* Install QC tracking so deferred callbacks' setQueryData calls are captured */
-					let trackedQC: { drain(): Array<{ data: unknown; key: unknown[]; staleTime?: number }> } | undefined;
-					if (config.queryClient) {
-						const { createTrackedQueryClient } = await import("../query-client");
-						const typed = config.queryClient as Parameters<typeof createTrackedQueryClient>[0];
-						trackedQC = createTrackedQueryClient(typed);
-					}
-
 					const entries: DeferredEntry[] = [];
 					for (const ctx of config.deferContexts.values()) {
 						for (const e of ctx.entries()) {
@@ -821,41 +826,53 @@ export function renderToStream(config: SSRConfig): SSRResult {
 					}
 					const escapedNonce = escapeAttr(config.nonce);
 					const esc = (s: string) => JSON.stringify(s).replace(/</g, "\\u003c");
-					await Promise.allSettled(
-						entries.map(async (entry) => {
-							const resolverKey = esc(`${entry.matchId}:${entry.key}`);
-							try {
-								const data = await entry.promise;
-								const json = JSON.stringify(data).replace(/</g, "\\u003c");
-								controller.enqueue(
-									encoder.encode(
-										`<script nonce="${escapedNonce}">(self.__flare_q=self.__flare_q||[]).push([${resolverKey},${json}])</script>`,
-									),
-								);
-							} catch (err) {
-								const msg = err instanceof Error ? err.message : String(err);
-								const safeMsg = esc(msg);
-								controller.enqueue(
-									encoder.encode(
-										`<script nonce="${escapedNonce}">(self.__flare_q=self.__flare_q||[]).push([${resolverKey},${safeMsg},true])</script>`,
-									),
-								);
-							}
-
-							/* Stream QC delta entries accumulated during this deferred resolve */
-							if (trackedQC) {
-								const qcEntries = trackedQC.drain();
-								for (const qcEntry of qcEntries) {
-									const qcJson = JSON.stringify(qcEntry).replace(/</g, "\\u003c");
+
+					const streamDeferred = async (trackedQC?: {
+						drain(): Array<{ data: unknown; key: unknown[]; staleTime?: number }>;
+					}) => {
+						await Promise.allSettled(
+							entries.map(async (entry) => {
+								const resolverKey = esc(`${entry.matchId}:${entry.key}`);
+								try {
+									const data = await entry.promise;
+									const json = JSON.stringify(data).replace(/</g, "\\u003c");
+									controller.enqueue(
+										encoder.encode(
+											`<script nonce="${escapedNonce}">(self.${GLOBAL_DEFER}=self.${GLOBAL_DEFER}||[]).push([${resolverKey},${json}])</script>`,
+										),
+									);
+								} catch (err) {
+									const msg = err instanceof Error ? err.message : String(err);
+									const safeMsg = esc(msg);
 									controller.enqueue(
 										encoder.encode(
-											`<script nonce="${escapedNonce}">(self.__flare_qc=self.__flare_qc||[]).push([${qcJson}])</script>`,
+											`<script nonce="${escapedNonce}">(self.${GLOBAL_DEFER}=self.${GLOBAL_DEFER}||[]).push([${resolverKey},${safeMsg},true])</script>`,
 										),
 									);
 								}
-							}
-						}),
-					);
+
+								if (trackedQC) {
+									const qcEntries = trackedQC.drain();
+									for (const qcEntry of qcEntries) {
+										const qcJson = JSON.stringify(qcEntry).replace(/</g, "\\u003c");
+										controller.enqueue(
+											encoder.encode(
+												`<script nonce="${escapedNonce}">(self.${GLOBAL_QUERIES}=self.${GLOBAL_QUERIES}||[]).push([${qcJson}])</script>`,
+											),
+										);
+									}
+								}
+							}),
+						);
+					};
+
+					if (config.queryClient) {
+						const { withTrackedQueryClient } = await import("../query-client");
+						const typed = config.queryClient as Parameters<typeof withTrackedQueryClient>[0];
+						await withTrackedQueryClient(typed, streamDeferred);
+					} else {
+						await streamDeferred();
+					}
 				}
 
 				controller.close();

package/src/state-parser/index.ts

@@ -57,6 +57,17 @@ export function isDeferredMarker(value: unknown): value is DeferredMarker {
 	return obj.__deferred === true && "key" in obj && typeof obj.key === "string";
 }
 
+const MAX_DEFERRED_WALK = 50;
+
+/** Prefetch stores `{ __deferred, key }` with no promise. Hydrated shells use `__key` + `promise`. */
+export function hasRawDeferredMarkers(data: unknown, depth = 0): boolean {
+	if (depth > MAX_DEFERRED_WALK) return false;
+	if (data === null || data === undefined || typeof data !== "object") return false;
+	if (isDeferredMarker(data) && !("promise" in data)) return true;
+	if (Array.isArray(data)) return data.some((v) => hasRawDeferredMarkers(v, depth + 1));
+	return Object.values(data as Record<string, unknown>).some((v) => hasRawDeferredMarkers(v, depth + 1));
+}
+
 export function hydrateLoaderData(matchId: string, data: unknown, resolvers: Map<string, DeferredResolver>): unknown {
 	if (data === null || data === undefined) return data;
 	if (typeof data !== "object") return data;
@@ -68,6 +79,10 @@ export function hydrateLoaderData(matchId: string, data: unknown, resolvers: Map
 			resolveFn = resolve;
 			rejectFn = reject;
 		});
+		/* Handler attached in the same tick as construction so a later
+		   reject() (NDJSON error, navigation cancel) is not unhandled
+		   before Await's then() attaches. Multiple handlers still fire. */
+		promise.catch(() => {});
 		resolvers.set(`${matchId}:${data.key}`, { reject: rejectFn, resolve: resolveFn });
 		return { __deferred: true, __key: data.key, promise };
 	}
@@ -86,15 +101,15 @@ export function hydrateLoaderData(matchId: string, data: unknown, resolvers: Map
 }
 
 /**
- * Register `self.__flare_r(resolverKey, data)` global so streamed `<script>` tags
- * from SSR deferred resolution can resolve hydrated promise shells.
+ * SSR deferred chunks push into `self.__flare_defer`. `__flare_r` / `__flare_re`
+ * are leftovers and are no longer installed.
  */
 declare global {
-	var __flare_q:
+	var __flare_defer:
 		| Array<[string, unknown, boolean?]>
 		| { push: (entry: [string, unknown, boolean?]) => number }
 		| undefined;
-	var __flare_qc: Array<[unknown]> | { push: (entry: [unknown]) => number } | undefined;
+	var __flare_queries: Array<[unknown]> | { push: (entry: [unknown]) => number } | undefined;
 	var __flare_r: ((key: string, data: unknown) => void) | undefined;
 	var __flare_re: ((key: string, message: string) => void) | undefined;
 }
@@ -102,7 +117,7 @@ declare global {
 /*
  * Multi-instance registry: supports multiple Flare apps hydrating on the same page.
  * Each call to installDeferredResolver registers its resolver map. The global
- * __flare_r/__flare_re/__flare_q search ALL active maps when resolving a key.
+ * `__flare_defer` push proxy searches ALL active maps when resolving a key.
  * Globals are only cleaned when every active map is drained AND no pending entries remain.
  */
 const activeInstances = new Set<Map<string, DeferredResolver>>();
@@ -131,7 +146,7 @@ function cleanupIfAllEmpty(): void {
 	}
 	globalThis.__flare_r = undefined;
 	globalThis.__flare_re = undefined;
-	globalThis.__flare_q = undefined;
+	globalThis.__flare_defer = undefined;
 	activeInstances.clear();
 }
 
@@ -140,7 +155,7 @@ function cleanupIfAllEmpty(): void {
  * then install live resolver for any late-arriving chunks.
  *
  * SSR scripts push `[key, data]` (or `[key, msg, true]` for errors)
- * into `self.__flare_q` array. This function drains them, then replaces
+ * into `self.__flare_defer` array. This function drains them, then replaces
  * the array push with a direct resolver so future chunks resolve immediately.
  *
  * Safe for multiple Flare instances on the same page — resolvers compose
@@ -149,8 +164,10 @@ function cleanupIfAllEmpty(): void {
 export function installDeferredResolver(resolvers: Map<string, DeferredResolver>): void {
 	if (typeof globalThis === "undefined") return;
 
-	/* Reset registry if globals were cleaned externally (e.g. tests) */
-	if (!globalThis.__flare_r && activeInstances.size > 0) {
+	/* Reset leftover instances when this is a new page load: no live proxy
+	 * (undefined after cleanup, or a fresh SSR array to drain). */
+	const deferIsLiveProxy = globalThis.__flare_defer !== undefined && !Array.isArray(globalThis.__flare_defer);
+	if (!deferIsLiveProxy && activeInstances.size > 0) {
 		activeInstances.clear();
 		pendingEntries.length = 0;
 	}
@@ -158,7 +175,7 @@ export function installDeferredResolver(resolvers: Map<string, DeferredResolver>
 	activeInstances.add(resolvers);
 
 	/* Drain any buffered entries from SSR script tags */
-	const queue = globalThis.__flare_q;
+	const queue = globalThis.__flare_defer;
 	if (Array.isArray(queue)) {
 		for (const entry of queue) {
 			resolveOrBuffer(entry[0], entry[1], Boolean(entry[2]));
@@ -174,28 +191,20 @@ export function installDeferredResolver(resolvers: Map<string, DeferredResolver>
 		}
 	}
 
-	/* Install live resolvers for chunks that stream after hydration */
-	globalThis.__flare_r = (key: string, data: unknown) => {
-		resolveOrBuffer(key, data, false);
-		cleanupIfAllEmpty();
-	};
-	globalThis.__flare_re = (key: string, message: string) => {
-		resolveOrBuffer(key, message, true);
-		cleanupIfAllEmpty();
-	};
-
 	/*
-	 * Trap __flare_q so late-arriving SSR script pushes resolve immediately.
-	 * SSR scripts do `(self.__flare_q=self.__flare_q||[]).push([...])` — after
+	 * Trap __flare_defer so late-arriving SSR script pushes resolve immediately.
+	 * SSR scripts do `(self.__flare_defer=self.__flare_defer||[]).push([...])` — after
 	 * drain, new pushes must route through the live resolver, not the array.
 	 */
-	globalThis.__flare_q = {
+	globalThis.__flare_defer = {
 		push(entry: [string, unknown, boolean?]) {
 			resolveOrBuffer(entry[0], entry[1], Boolean(entry[2]));
 			cleanupIfAllEmpty();
 			return 0;
 		},
 	};
+	globalThis.__flare_r = undefined;
+	globalThis.__flare_re = undefined;
 
 	/* If no resolvers needed (all data was instant), clean up immediately */
 	cleanupIfAllEmpty();
@@ -205,9 +214,12 @@ export function installDeferredResolver(resolvers: Map<string, DeferredResolver>
  * Drain buffered deferred QC entries from SSR streamed `<script>` tags,
  * then install live proxy for late-arriving entries.
  *
- * SSR scripts push `[{data, key, staleTime?}]` into `self.__flare_qc` array.
+ * SSR scripts push `[{data, key, staleTime?}]` into `self.__flare_queries` array.
  * This function drains them, then replaces the array with a push-proxy
  * so future scripts hydrate immediately.
+ *
+ * Call after `useQuery` observers have attached (a microtask after
+ * `solidHydrate`). Draining earlier writes into a cache with no subscribers.
  */
 export function installQueryCacheResolver(queryClient: unknown): void {
 	if (typeof globalThis === "undefined") return;
@@ -228,7 +240,7 @@ export function installQueryCacheResolver(queryClient: unknown): void {
 	}
 
 	/* Drain any buffered entries from SSR script tags */
-	const queue = globalThis.__flare_qc;
+	const queue = globalThis.__flare_queries;
 	if (Array.isArray(queue)) {
 		for (const entry of queue) {
 			applyEntry(entry[0]);
@@ -236,7 +248,7 @@ export function installQueryCacheResolver(queryClient: unknown): void {
 	}
 
 	/* Install push-proxy for late-arriving SSR scripts */
-	globalThis.__flare_qc = {
+	globalThis.__flare_queries = {
 		push(entry: [unknown]) {
 			applyEntry(entry[0]);
 			return 0;