@lovrozagar/flare 0.1.2 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # Flare
 
-Solid + Vite meta-framework. You declare pages and layouts with a typed builder. The server streams HTML (`renderToStream`). Later navigations speak NDJSON (`x-d: 1`). Prefetch, ISR, deferred loaders, and forms reuse that protocol.
+Solid + Vite meta-framework. You declare pages and layouts with a typed builder. The server streams HTML (`renderToStream`). Later navigations speak NDJSON (`flare-data: 1`). Prefetch, ISR, deferred loaders, and forms reuse that protocol.
 
 This repo is the source of [`@lovrozagar/flare`](https://www.npmjs.com/package/@lovrozagar/flare) `0.1.1`. The CLI binary is `flare`.
 
@@ -123,7 +123,7 @@ npm add @lovrozagar/flare
 pnpm add @lovrozagar/flare
 ```
 
-Peers: `solid-js`, `vite`, `vite-plugin-solid`. Optional: `sharp` (images), `isbot` (skip locale cookies for bots), `@tanstack/solid-query` (query), `@tanstack/query-broadcast-client-experimental` (query broadcast), `oxc-parser`, `oxc-resolver`.
+Peers: `solid-js`, `@solidjs/web`, `@solidjs/vite-plugin`, `vite`. Optional: `sharp` (images), `isbot` (skip locale cookies for bots), `@tanstack/solid-query` (query), `@tanstack/query-broadcast-client-experimental` (query broadcast), `oxc-parser`, `oxc-resolver`.
 
 The CLI is a workspace package (`@flare/cli`, binary `flare`). In this repo it is on the path via workspace linking. A published consumer uses `flare init` after adding the package.
 
@@ -132,7 +132,7 @@ The CLI is a workspace package (`@flare/cli`, binary `flare`). In this repo it i
 ```bash
 mkdir my-app && cd my-app
 bun init -y
-bun add @lovrozagar/flare solid-js vite vite-plugin-solid
+bun add @lovrozagar/flare solid-js @solidjs/web vite @solidjs/vite-plugin
 flare init
 bun run dev
 ```
@@ -786,7 +786,7 @@ import { DirectionScript } from "@lovrozagar/flare/direction";
 </head>;
 ```
 
-- **Locale** — optional `[[locale]]` segment or prefix. Cookie `flare.locale` + `Accept-Language`. Default locale is stripped (`/en/about` → `/about`). Playwright / bot UAs skip Set-Cookie (`isbot`). Prefetch (`x-p: 1`) never writes the cookie.
+- **Locale** — optional `[[locale]]` segment or prefix. Cookie `flare.locale` + `Accept-Language`. Default locale is stripped (`/en/about` → `/about`). Playwright / bot UAs skip Set-Cookie (`isbot`). Prefetch (`flare-prefetch: 1`) never writes the cookie.
 - **Theme** — `data-theme`, system preference, `localStorage`.
 - **Direction** — `dir` / `data-dir`.
 
@@ -908,7 +908,7 @@ import { BroadcastProvider } from "@lovrozagar/flare/broadcast";
 createRouter({ queryClientGetter: getQueryClient });
 ```
 
-SSR dehydrates into the stream (`__flare_qc` / `t:"q"`). `useSuspenseQuery` suspends until the dehydrated entry is ready. Optional `BroadcastProvider` invalidates across tabs.
+SSR dehydrates into the stream (`__flare_queries` / `t:"q"`). `useSuspenseQuery` suspends until the dehydrated entry is ready. Optional `BroadcastProvider` invalidates across tabs.
 
 ```ts
 import { createQueryClientGetter } from "@lovrozagar/flare/query-client";
@@ -993,7 +993,28 @@ Playwright helpers: hydration, FlareState shape, console-error filters. Product
 
 ## NDJSON protocol
 
-SPA / prefetch / data requests send `x-d: 1`. Prefetch also sends `x-p: 1`. Stale match skip uses `x-m`.
+SPA / prefetch / data requests send `flare-data: 1`. Prefetch also sends `flare-prefetch: 1`. Stale match skip uses `flare-stale`. Flag value is always `"1"`. Headers are lowercase (HTTP/2 / Node). NDJSON `t` codes and FlareState keys stay short.
+
+| Request           | Meaning                                           |
+| ----------------- | ------------------------------------------------- |
+| `flare-data`      | NDJSON data request. `Vary` always includes this. |
+| `flare-prefetch`  | Prefetch (no locale cookie commit)                |
+| `flare-stale`     | Comma-separated match ids the client already has  |
+| `flare-isr`       | Internal ISR background re-render                 |
+| `flare-prerender` | Build-time prerender fetch                        |
+
+| Response       | Meaning                  |
+| -------------- | ------------------------ |
+| `flare-cache`  | `HIT` / `MISS` / `STALE` |
+| `flare-render` | `ISR` / `SSG` / `SSR`    |
+
+| Path / HTML                     | Meaning                                    |
+| ------------------------------- | ------------------------------------------ |
+| `/_flare/server-fn/{id}/{name}` | Server functions                           |
+| `flare_fn`                      | Hidden form field for no-JS POST           |
+| `data-flare-hydrated`           | Set on `<html>` after `solidHydrate`       |
+| `__flare_defer`                 | Window queue for SSR deferred chunks       |
+| `__flare_queries`               | Window queue for SSR query-cache dehydrate |
 
 | `t` | Meaning         |
 | --- | --------------- |
@@ -1053,7 +1074,7 @@ export default defineConfig({
 | `ignorePrefix`                         | extra ignored folder names                  |                                                              |
 | `port`                                 | Vite `server.port` (overrides CLI `--port`) |                                                              |
 | `alias`                                | Vite alias                                  |                                                              |
-| `solid`                                | passed to `vite-plugin-solid`               |                                                              |
+| `solid`                                | passed to `@solidjs/vite-plugin`            | `ssr: true` is forced; `start: true` is rejected             |
 
 `dev: false` turns every `dev.*` flag off. Dev dashboard is `@node-only` in e2e (not on Workers).
 
@@ -1141,7 +1162,7 @@ Requires [Bun](https://bun.sh) 1.3+ and TypeScript 7.
 bun install
 bun run test                 # core unit
 bun run test:cli             # CLI unit
-bun run test:all             # unit + all e2e apps on node
+bun run test:all             # unit + build + e2e apps on node (dev then prod)
 bun run test:all -- --env bun
 bun run typecheck
 bun run typecheck:consumers
@@ -1149,7 +1170,7 @@ bun run lint
 bun run fmt:check
 ```
 
-GitHub Actions (`.github/workflows/ci.yml`): `test` runs typecheck, fmt, lint, unit. `e2e` is a matrix of node / bun / workers / deno.
+GitHub Actions (`.github/workflows/ci.yml`): `test` runs typecheck, fmt, lint, unit. `e2e` is a matrix of node / bun / workers / deno, each in Vite **dev** and (except deno/firefox) **prod** (`vite preview`).
 
 Release: bump `packages/core/package.json`, commit, tag `vX.Y.Z` matching that version, and push the tag. `.github/workflows/release.yml` publishes `@lovrozagar/flare` to npm via GitHub Actions OIDC (no npm token) and opens the GitHub Release. The npm trusted publisher must name this file `release.yml`.
 
@@ -1172,16 +1193,18 @@ Do not weaken `strict` or add `as any` to make typecheck pass.
 
 ### Test matrix
 
-| Command                    | What it proves                 |
-| -------------------------- | ------------------------------ |
-| `bun run test`             | Core unit + integration        |
-| `bun run test:cli`         | CLI unit                       |
-| `bun run test:e2e`         | Playwright, every app × node   |
-| `bun run test:e2e:bun`     | Same tests, Bun listen         |
-| `bun run test:e2e:workers` | Same tests, local workerd      |
-| `bun run test:e2e:deno`    | Same tests, Deno               |
-| `bun run test:e2e:firefox` | Same tests, Firefox (dev only) |
-| `bun run test:e2e:prod`    | Node, `TEST_MODE=prod`         |
+| Command                         | What it proves                             |
+| ------------------------------- | ------------------------------------------ |
+| `bun run test`                  | Core unit + integration                    |
+| `bun run test:cli`              | CLI unit                                   |
+| `bun run test:e2e`              | Playwright, every app × node, Vite **dev** |
+| `bun run test:e2e:prod`         | Same tests, `vite build` + **preview**     |
+| `bun run test:e2e:bun`          | Same tests, Bun listen (dev)               |
+| `bun run test:e2e:bun:prod`     | Bun listen, prod preview                   |
+| `bun run test:e2e:workers`      | Same tests, local workerd (dev)            |
+| `bun run test:e2e:workers:prod` | workerd, prod preview                      |
+| `bun run test:e2e:deno`         | Same tests, Deno (dev)                     |
+| `bun run test:e2e:firefox`      | Same tests, Firefox (**dev only**)         |
 
 ```bash
 bun run test:e2e -- --app product

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lovrozagar/flare",
-	"version": "0.1.2",
+	"version": "0.2.1",
 	"description": "Solid meta-framework. Server-driven, NDJSON streaming, renderToStream.",
 	"keywords": [
 		"flare",
@@ -107,6 +107,8 @@
 		"@capsizecss/metrics": "catalog:",
 		"@formatjs/intl-localematcher": "catalog:",
 		"@solidjs/testing-library": "catalog:",
+		"@solidjs/vite-plugin": "catalog:",
+		"@solidjs/web": "catalog:",
 		"@tanstack/query-broadcast-client-experimental": "catalog:",
 		"@tanstack/solid-query": "catalog:",
 		"@types/negotiator": "catalog:",
@@ -121,14 +123,15 @@
 		"solid-js": "catalog:",
 		"typescript": "catalog:",
 		"vite": "catalog:",
-		"vite-plugin-solid": "catalog:",
 		"vitest": "catalog:"
 	},
 	"peerDependencies": {
 		"@babel/parser": ">=8.0.0",
 		"@formatjs/intl-localematcher": ">=0.6.0",
+		"@solidjs/vite-plugin": ">=3.0.0-next.0",
+		"@solidjs/web": ">=2.0.0-rc.0",
 		"@tanstack/query-broadcast-client-experimental": ">=5.0.0",
-		"@tanstack/solid-query": ">=5.0.0",
+		"@tanstack/solid-query": ">=6.0.0-rc.0",
 		"isbot": ">=5.0.0",
 		"magic-string": ">=0.30.0",
 		"negotiator": ">=1.0.0",
@@ -136,9 +139,8 @@
 		"oxc-parser": ">=0.139.0",
 		"oxc-resolver": ">=11.23.0",
 		"sharp": ">=0.33.0",
-		"solid-js": ">=1.9.0",
-		"vite": ">=8.0.0",
-		"vite-plugin-solid": ">=2.0.0"
+		"solid-js": ">=2.0.0-rc.0",
+		"vite": ">=8.0.0"
 	},
 	"peerDependenciesMeta": {
 		"@formatjs/intl-localematcher": {

package/src/broadcast/index.ts

@@ -42,7 +42,7 @@ export function createBroadcastSignal<T>(key: string, initialValue: T): [() => T
 
 	let entry = registry.get(key);
 	if (!entry) {
-		const [value, setValue] = createSignal<T>(initialValue);
+		const [value, setValue] = createSignal(initialValue as Exclude<T, Function>);
 		entry = {
 			refCount: 0,
 			signal: [value, setValue as (v: unknown) => void],

package/src/broadcast/provider.tsx

@@ -1,7 +1,7 @@
-import type { JSX } from "solid-js";
+import type { JSX } from "@solidjs/web";
 import type { InternalChannel } from "./channel.ts";
 import { BroadcastCtx, noopChannel } from "./context.ts";
 
 export function BroadcastProvider(props: { children: JSX.Element; value?: InternalChannel }): JSX.Element {
-	return <BroadcastCtx.Provider value={props.value ?? noopChannel}>{props.children}</BroadcastCtx.Provider>;
+	return <BroadcastCtx value={props.value ?? noopChannel}>{props.children}</BroadcastCtx>;
 }

package/src/caches/index.ts

@@ -1,8 +1,34 @@
 import type { HeadConfig } from "../route-builder/types.ts";
 
+export function resolveCacheTags(
+	cache:
+		| {
+				cdn?: { tags?: string[] | ((ctx: { params: Record<string, string | string[]> }) => string[]) } | false;
+				ssr?: { tags?: string[] | ((ctx: { params: Record<string, string | string[]> }) => string[]) } | false;
+		  }
+		| undefined,
+	params: Record<string, string | string[]>,
+): string[] | undefined {
+	if (!cache) return undefined;
+	const tags: string[] = [];
+	const push = (
+		src: { tags?: string[] | ((ctx: { params: Record<string, string | string[]> }) => string[]) } | false | undefined,
+	) => {
+		if (!src || !src.tags) return;
+		const list = typeof src.tags === "function" ? src.tags({ params }) : src.tags;
+		for (const t of list) {
+			if (typeof t === "string" && t.length > 0 && !tags.includes(t)) tags.push(t);
+		}
+	};
+	push(cache.cdn);
+	push(cache.ssr);
+	return tags.length > 0 ? tags : undefined;
+}
+
 export interface CachedMatch {
 	data: unknown;
 	error?: unknown;
+	gcTime?: number;
 	hasDeferred?: boolean;
 	headConfig?: HeadConfig;
 	invalid: boolean;

package/src/components/await.tsx

@@ -1,4 +1,5 @@
-import { batch, createEffect, createSignal, type JSX } from "solid-js";
+import { createEffect, createMemo, createSignal, untrack } from "solid-js";
+import type { JSX } from "@solidjs/web";
 
 export interface Deferred<T> {
 	__deferred: true;
@@ -47,8 +48,10 @@ export function getResolvedError(value: unknown): Error | undefined {
 }
 
 export function Await<T>(props: AwaitProps<T>): JSX.Element {
-	const initialResolved = getResolvedValue(props.promise);
-	const initialError = getResolvedError(props.promise);
+	/* Snapshot only — `createEffect` below tracks `props.promise` for updates. */
+	const initialPromise = untrack(() => props.promise);
+	const initialResolved = getResolvedValue(initialPromise);
+	const initialError = getResolvedError(initialPromise);
 
 	function computeInitialStatus(): AwaitStatus {
 		if (initialResolved !== undefined) return "success";
@@ -57,10 +60,10 @@ export function Await<T>(props: AwaitProps<T>): JSX.Element {
 	}
 
 	const [status, setStatus] = createSignal<AwaitStatus>(computeInitialStatus());
-	const [data, setData] = createSignal<T | undefined>(initialResolved);
+	const [data, setData] = createSignal<T | undefined>(initialResolved as Exclude<T | undefined, Function>);
 	const [error, setError] = createSignal<Error | undefined>(initialError);
 
-	let currentPromise = getPromise(props.promise);
+	let currentPromise = getPromise(initialPromise);
 
 	if (initialResolved === undefined && !initialError && currentPromise) {
 		trackPromise(currentPromise);
@@ -70,18 +73,14 @@ export function Await<T>(props: AwaitProps<T>): JSX.Element {
 		p.then(
 			(result) => {
 				if (currentPromise === p) {
-					batch(() => {
-						setData(() => result);
-						setStatus("success");
-					});
+					setData(() => result);
+					setStatus("success");
 				}
 			},
 			(err: unknown) => {
 				if (currentPromise === p) {
-					batch(() => {
-						setError(() => (err instanceof Error ? err : new Error(String(err))));
-						setStatus("error");
-					});
+					setError(() => (err instanceof Error ? err : new Error(String(err))));
+					setStatus("error");
 				}
 			},
 		);
@@ -90,43 +89,41 @@ export function Await<T>(props: AwaitProps<T>): JSX.Element {
 	function reset(): void {
 		const p = getPromise(props.promise);
 		currentPromise = p;
-		batch(() => {
-			setStatus("pending");
-			setData(undefined);
-			setError(undefined);
-		});
+		setStatus("pending");
+		setData(undefined);
+		setError(undefined);
 		if (p) trackPromise(p);
 	}
 
-	/* Watch for promise prop changes */
-	createEffect(() => {
-		const newPromise = getPromise(props.promise);
-		if (newPromise === currentPromise) return;
-		currentPromise = newPromise;
+	/* Watch for promise prop changes. Wrap in an object so a Promise value is
+	   not treated as an async computation (Solid 2 unwraps returned Promises). */
+	createEffect(
+		() => ({ promise: props.promise }),
+		({ promise }) => {
+			const newPromise = getPromise(promise);
+			if (newPromise === currentPromise) return;
+			currentPromise = newPromise;
 
-		const resolved = getResolvedValue(props.promise);
-		const resolvedError = getResolvedError(props.promise);
+			const resolved = getResolvedValue(promise);
+			const resolvedError = getResolvedError(promise);
 
-		if (resolved !== undefined) {
-			batch(() => {
+			if (resolved !== undefined) {
 				setData(() => resolved);
 				setStatus("success");
-			});
-			return;
-		}
-		if (resolvedError) {
-			batch(() => {
+				return;
+			}
+			if (resolvedError) {
 				setError(() => resolvedError);
 				setStatus("error");
-			});
-			return;
-		}
+				return;
+			}
 
-		setStatus("pending");
-		if (newPromise) trackPromise(newPromise);
-	});
+			setStatus("pending");
+			if (newPromise) trackPromise(newPromise);
+		},
+	);
 
-	return (() => {
+	return createMemo(() => {
 		const s = status();
 		if (s === "success") {
 			return props.children(data() as T);

package/src/components/dev-error-overlay.tsx

@@ -1,5 +1,6 @@
-import { createSignal, For, type JSX, onCleanup, onMount, Show } from "solid-js";
-import { Portal } from "solid-js/web";
+import { createSignal, For, onSettled, Show } from "solid-js";
+import type { JSX } from "@solidjs/web";
+import { Portal } from "@solidjs/web";
 import { createDevErrorStore, type DevErrorStore } from "./index.ts";
 
 let globalStore: DevErrorStore | undefined;
@@ -34,16 +35,14 @@ export function DevErrorOverlay(): JSX.Element {
 		refresh();
 	}
 
-	onMount(() => {
+	onSettled(() => {
 		if (typeof window === "undefined") return;
 		window.addEventListener("error", handleWindowError);
 		window.addEventListener("unhandledrejection", handleUnhandledRejection);
-	});
-
-	onCleanup(() => {
-		if (typeof window === "undefined") return;
-		window.removeEventListener("error", handleWindowError);
-		window.removeEventListener("unhandledrejection", handleUnhandledRejection);
+		return () => {
+			window.removeEventListener("error", handleWindowError);
+			window.removeEventListener("unhandledrejection", handleUnhandledRejection);
+		};
 	});
 
 	function dismiss(id: string): void {

package/src/components/direction-script.tsx

@@ -1,5 +1,5 @@
-import type { JSX } from "solid-js";
-import { NoHydration } from "solid-js/web";
+import type { JSX } from "@solidjs/web";
+import { NoHydration } from "@solidjs/web";
 import type { DirectionConfig } from "../direction.ts";
 import { getDirectionScript } from "../direction.ts";
 import { useSSRContext } from "./ssr-context.tsx";

package/src/components/locale-script.tsx

@@ -1,5 +1,5 @@
-import type { JSX } from "solid-js";
-import { NoHydration } from "solid-js/web";
+import type { JSX } from "@solidjs/web";
+import { NoHydration } from "@solidjs/web";
 import type { LocaleConfig } from "../locale/index.tsx";
 import { getLocaleScript } from "../locale/index.tsx";
 import { useSSRContext } from "./ssr-context.tsx";

package/src/components/reset-css.tsx

@@ -1,4 +1,4 @@
-import type { JSX } from "solid-js";
+import type { JSX } from "@solidjs/web";
 import { useSSRContext } from "./ssr-context.tsx";
 
 /* Duplicated from index.ts to avoid circular import (index re-exports this component) */

package/src/components/ssr-context.tsx

@@ -1,4 +1,5 @@
-import { createContext, type JSX, sharedConfig, useContext } from "solid-js";
+import { createContext, useContext } from "solid-js";
+import type { JSX } from "@solidjs/web";
 import type { DirectionConfig } from "../direction.ts";
 import type { LocaleConfig } from "../locale/index.tsx";
 import type { HeadConfig } from "../route-builder/types.ts";
@@ -15,23 +16,15 @@ export interface SSRContextValue {
 	theme?: ThemeConfig;
 }
 
-const SSRCtx = createContext<SSRContextValue>();
+const SSRCtx = createContext<SSRContextValue | null>(null);
 
-export function setSSRContext(value: SSRContextValue): void {
-	if (sharedConfig.context) {
-		(sharedConfig.context as Record<string, unknown>).flare = value;
-	}
-}
+/** @deprecated Wrap the tree with SSRContextProvider. Solid 2 has no sharedConfig.context. */
+export function setSSRContext(_value: SSRContextValue): void {}
 
 export function useSSRContext(): SSRContextValue | undefined {
-	/* SSR path: read from sharedConfig.context */
-	if (sharedConfig.context) {
-		return (sharedConfig.context as Record<string, unknown>).flare as SSRContextValue | undefined;
-	}
-	/* Testing fallback: read from Solid context provider */
-	return useContext(SSRCtx);
+	return useContext(SSRCtx) ?? undefined;
 }
 
 export function SSRContextProvider(props: { children: JSX.Element; value: SSRContextValue }): JSX.Element {
-	return <SSRCtx.Provider value={props.value}>{props.children}</SSRCtx.Provider>;
+	return <SSRCtx value={props.value}>{props.children}</SSRCtx>;
 }

package/src/components/theme-script.tsx

@@ -1,5 +1,5 @@
-import type { JSX } from "solid-js";
-import { NoHydration } from "solid-js/web";
+import type { JSX } from "@solidjs/web";
+import { NoHydration } from "@solidjs/web";
 import type { ThemeConfig } from "../theme.ts";
 import { getThemeScript } from "../theme.ts";
 import { useSSRContext } from "./ssr-context.tsx";

package/src/components/view-transition-css.tsx

@@ -1,4 +1,4 @@
-import type { JSX } from "solid-js";
+import type { JSX } from "@solidjs/web";
 import { useSSRContext } from "./ssr-context.tsx";
 
 /* Duplicated from index.ts to avoid circular import (index re-exports this component) */

package/src/defer/index.ts

@@ -80,3 +80,25 @@ export function isDeferred(value: unknown): value is Deferred<unknown> {
 		(value as Record<string, unknown>).__deferred === true
 	);
 }
+
+/** True if `data` is or contains a deferred marker. Used to skip SSR store cache of unresolved streams. */
+export function containsDeferred(data: unknown, seen?: WeakSet<object>): boolean {
+	if (data === null || data === undefined || typeof data !== "object") return false;
+	if (isDeferred(data)) return true;
+
+	const tracking = seen ?? new WeakSet<object>();
+	if (tracking.has(data as object)) return false;
+	tracking.add(data as object);
+
+	if (Array.isArray(data)) {
+		for (const item of data) {
+			if (containsDeferred(item, tracking)) return true;
+		}
+		return false;
+	}
+
+	for (const value of Object.values(data as Record<string, unknown>)) {
+		if (containsDeferred(value, tracking)) return true;
+	}
+	return false;
+}

package/src/direction/index.tsx

@@ -1,14 +1,5 @@
-import {
-	createContext,
-	createEffect,
-	createSignal,
-	type JSX,
-	on,
-	onCleanup,
-	onMount,
-	sharedConfig,
-	useContext,
-} from "solid-js";
+import { createContext, createEffect, createSignal, onSettled, sharedConfig, untrack, useContext } from "solid-js";
+import { isServer, type JSX } from "@solidjs/web";
 
 export type Direction = "ltr" | "rtl";
 
@@ -60,14 +51,9 @@ export interface DirectionContextValue {
 	toggleDirection: () => void;
 }
 
-const DirectionCtx = createContext<DirectionContextValue>();
+const DirectionCtx = createContext<DirectionContextValue | null>(null);
 
 export function DirectionProvider(props: { children: JSX.Element; config?: DirectionConfig }): JSX.Element {
-	/* SSR: pass through children (context not needed on server, scripts handle direction) */
-	if (sharedConfig.context) {
-		return props.children;
-	}
-
 	const cfg: Required<DirectionConfig> = {
 		attribute: props.config?.attribute ?? DEFAULT_CONFIG.attribute,
 		defaultDir: props.config?.defaultDir ?? DEFAULT_CONFIG.defaultDir,
@@ -75,9 +61,12 @@ export function DirectionProvider(props: { children: JSX.Element; config?: Direc
 		storageKey: props.config?.storageKey ?? DEFAULT_CONFIG.storageKey,
 	};
 
-	/* Read initial direction from localStorage, DOM dir attr, or default */
+	const hydrating = isServer || !!sharedConfig.hydrating;
+
+	/* During SSR + hydration, start from defaultDir so the tree matches.
+	   DirectionScript already applied localStorage to <html> before first paint. */
 	let initial: Direction = cfg.defaultDir;
-	if (typeof localStorage !== "undefined") {
+	if (typeof localStorage !== "undefined" && !hydrating) {
 		try {
 			const stored = localStorage.getItem(cfg.storageKey);
 			if (stored === "ltr" || stored === "rtl") {
@@ -87,7 +76,7 @@ export function DirectionProvider(props: { children: JSX.Element; config?: Direc
 			/* noop */
 		}
 	}
-	if (initial === cfg.defaultDir && typeof document !== "undefined") {
+	if (initial === cfg.defaultDir && typeof document !== "undefined" && !hydrating) {
 		const domDir = document.documentElement.getAttribute("dir");
 		if (domDir === "ltr" || domDir === "rtl") {
 			initial = domDir;
@@ -96,17 +85,34 @@ export function DirectionProvider(props: { children: JSX.Element; config?: Direc
 
 	const [direction, setDirectionSignal] = createSignal<Direction>(initial);
 
-	/* Sync direction to DOM */
-	createEffect(() => {
-		const dir = direction();
+	const applyToDocument = (dir: Direction): void => {
 		if (typeof document === "undefined") return;
 		const el = document.documentElement;
 		el.setAttribute(cfg.attribute, dir);
 		el.setAttribute("dir", dir);
+	};
+
+	if (!hydrating) {
+		applyToDocument(untrack(direction));
+	}
+
+	/* After hydrate, sync from localStorage so useDirection() matches DirectionScript. */
+	onSettled(() => {
+		if (typeof localStorage === "undefined") return;
+		try {
+			const stored = localStorage.getItem(cfg.storageKey);
+			if ((stored === "ltr" || stored === "rtl") && stored !== untrack(direction)) {
+				setDirectionSignal(stored);
+			}
+		} catch {
+			/* noop */
+		}
+		applyToDocument(untrack(direction));
 	});
 
 	/* Cross-tab sync: StorageEvent fires in OTHER tabs only */
-	onMount(() => {
+	onSettled(() => {
+		if (typeof window === "undefined") return;
 		const handler = (e: StorageEvent) => {
 			if (e.key !== cfg.storageKey || e.storageArea !== localStorage) return;
 			const v = e.newValue;
@@ -115,22 +121,41 @@ export function DirectionProvider(props: { children: JSX.Element; config?: Direc
 			}
 		};
 		window.addEventListener("storage", handler);
-		onCleanup(() => window.removeEventListener("storage", handler));
+		return () => window.removeEventListener("storage", handler);
 	});
 
-	/* Persist to localStorage on changes */
-	createEffect(
-		on(
-			direction,
-			(dir) => {
+	/* After Solid hydrates <html> it may drop DirectionScript's dir. Re-apply. */
+	let skipFirst = true;
+	createEffect(direction, (dir) => {
+		if (typeof document === "undefined") return;
+		if (skipFirst) {
+			skipFirst = false;
+			let visual: Direction = dir;
+			if (typeof localStorage !== "undefined") {
 				try {
-					localStorage.setItem(cfg.storageKey, dir);
+					const stored = localStorage.getItem(cfg.storageKey);
+					if (stored === "ltr" || stored === "rtl") visual = stored;
 				} catch {
 					/* noop */
 				}
-			},
-			{ defer: true },
-		),
+			}
+			applyToDocument(visual);
+			return;
+		}
+		applyToDocument(dir);
+	});
+
+	/* Persist to localStorage on changes (not initial — it was read from there) */
+	createEffect(
+		direction,
+		(dir) => {
+			try {
+				localStorage.setItem(cfg.storageKey, dir);
+			} catch {
+				/* noop */
+			}
+		},
+		{ defer: true },
 	);
 
 	const setDirection = (dir: Direction): void => {
@@ -138,7 +163,7 @@ export function DirectionProvider(props: { children: JSX.Element; config?: Direc
 	};
 
 	const toggleDirection = (): void => {
-		const current = direction();
+		const current = untrack(direction);
 		setDirection(current === "ltr" ? "rtl" : "ltr");
 	};
 
@@ -153,7 +178,7 @@ export function DirectionProvider(props: { children: JSX.Element; config?: Direc
 		toggleDirection,
 	};
 
-	return <DirectionCtx.Provider value={value}>{props.children}</DirectionCtx.Provider>;
+	return <DirectionCtx value={value}>{props.children}</DirectionCtx>;
 }
 
 export function useDirection(): DirectionContextValue {