@quark-fw/plugin-react 0.1.26 → 0.1.27

package/README.md

@@ -0,0 +1,60 @@
+# @quark-fw/plugin-react
+
+React 19 SSR frontend for Quark apps: an express server with vite in dev and a prebuilt bundle in production, file-based routing over `src/frontend/Pages`, streaming render with the store cache inlined for hydration, per-page SEO meta, optional i18n with locale prefixes, Mantine providers, request ids and security headers on every response.
+
+## Install
+
+```sh
+npm i @quark-fw/plugin-react
+```
+
+Peers: `@quark-fw/core`, `@quark-fw/store`, `react`, `react-dom`, `react-router-dom`, `vite`, `@vitejs/plugin-react`, `@mantine/core`, `@mantine/dates`, `@mantine/modals`, `@mantine/notifications`. The app runs the backend with `tsx` (`tsx watch src/index.ts` in dev, `NODE_ENV=production tsx src/index.ts` in prod).
+
+## Usage
+
+```ts
+// src/index.ts — react goes last: it mounts the routes other plugins registered
+import "@quark-fw/plugin-trpc";
+import "@quark-fw/plugin-react"; // provides quark.react; the server starts in onReady
+import "./router/index.js";
+
+quark.react.port.value = Number(process.env.PORT) || 3001;
+quark.react.lang.value = "ru"; // <html lang> for apps without i18n
+quark.react.favicon.value = IDLE_FAVICON; // path or data-URI; empty string = no <link rel="icon">
+
+// src/build.ts — `npm run build` is `tsx src/build.ts`
+import { buildApp } from "@quark-fw/plugin-react/src/build.js";
+await buildApp();
+```
+
+```tsx
+// src/frontend/Pages/Main/Page.tsx → "/"
+import { createPageMeta } from "@quark-fw/plugin-react/src/seo/createPageMeta.js";
+import type { UglyPageProps } from "@quark-fw/plugin-react/src/Router/Router";
+
+function Page(_props: UglyPageProps) { /* ... */ }
+Page.meta = createPageMeta({
+  title: async ({ store }) => (await store.tiny.auth.me.getPromise()) ? "Todo" : "Todo — sign in",
+  description: "...",
+  robots: "noindex",
+});
+export default Page;
+```
+
+App contract (the vite root is `src/frontend`; the plugin owns `entry-client.tsx` / `entry-server.tsx` and discovers app files with `import.meta.glob`):
+
+- `Pages/**/Page.tsx` — a page; the path is the route: `Main/Page.tsx` → `/`, `Projects/[id]/Page.tsx` → `/projects/:id`, `[...rest]` → `*`, lowercased. Optional `Layout.tsx` in a folder wraps everything below it (`UglyLayoutProps` with `children`), `LayoutReset.tsx` stops inheriting outer layouts. A page may export `meta` (`createPageMeta`): `title`, `description`, `robots`, `og`, `jsonLD`, `breadcrumbs`, `status`, `redirect`, `canonical` — each a value or a (possibly async) function of `{ store, params, locale, origin, query }`, resolved on the server before the stream starts and again on client navigation.
+- `theme.ts` — exports `appTheme` (Mantine `createTheme`); imported as the virtual module `/theme.ts`.
+- `i18n.ts` (optional) — exports `i18nConfig = defineI18nConfig({ locales, defaultLocale, urlPrefix? })`; dictionaries in `locales/<lang>/<namespace>.ts`, read with `useI18n()`. With a config, URLs carry `/<locale>` prefixes, a bare path 302-redirects to the locale from the `locale` cookie or `Accept-Language`, and the head gets an hreflang cluster. `urlPrefix: false` is honoured only with a single locale.
+- `tsconfig.json`, `postcss.config.cjs` for Mantine, `types.d.ts` for CSS modules.
+- `static/` at the app root (optional) is served as-is in dev and copied into `build/static` by the build.
+
+How it works: `onReady` creates the express app, applies `requestContextMiddleware` (accepts an incoming `X-Request-Id` matching `[A-Za-z0-9._-]{1,128}` or generates a uuid, echoes it in the response, exposes it to the logger through AsyncLocalStorage and writes an access line per request — except `/assets/`), disables `x-powered-by`, adds `securityHeadersMiddleware` (`X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`, `Referrer-Policy: strict-origin-when-cross-origin`, and `Strict-Transport-Security` only when `req.secure`; no CSP because SSR inlines scripts), then the pre-middleware of other plugins (session, passport), their routes (`/api/trpc`, `/healthz`, ...), static files and finally the SSR middleware. Trailing slashes 301-redirect to the canonical form.
+
+During render the store talks to tRPC through one of three transports, in priority order: `SSR_TRPC_URL` (HTTP to another process, cookie forwarded), the in-process router of `@quark-fw/plugin-trpc` (no HTTP, same `req`/`res` context), or a loopback HTTP call to its own port. Resolved cache entries are written into `window.cache` as the stream goes so the client hydrates without refetching. Changing `quark.react.port` restarts the listener; `onDestroy` closes the server and vite.
+
+Production: `buildApp()` writes a client bundle with a manifest to `build/client`, an SSR bundle to `build/server/entry-server.js` and copies `static/`; the server refuses to start without them. Hashed `/assets` are served with `immutable, max-age=1y`.
+
+Env: `PORT` (default 3000; the apps override it through `quark.react.port`), `NODE_ENV` (`production` switches from vite to the build), `TRUST_PROXY` (express `trust proxy`: a number is the count of trusted hops — `1` behind Coolify/Traefik —, `true` trusts every `X-Forwarded-*`, anything else is a list of addresses or subnets; without it `req.secure` is false behind TLS termination, so no HSTS and no secure cookies), `SSR_TRPC_URL` (external tRPC endpoint for SSR, overrides the in-process router), `PUBLIC_ORIGIN` (canonical `https://host` for canonical / og:url / hreflang / JSON-LD; otherwise taken from the request), `INJECT_HTML` (operator markup — counters, site verification — appended as-is to the end of `<head>`).
+
+Part of the [Quark framework](https://www.npmjs.com/package/@quark-fw/core).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quark-fw/plugin-react",
-	"version": "0.1.26",
+	"version": "0.1.27",
 	"main": "src/index.ts",
 	"types": "src/index.ts",
 	"type": "module",
@@ -22,8 +22,8 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@quark-fw/atom": "0.1.26",
-		"@quark-fw/plugin": "0.1.26",
+		"@quark-fw/atom": "0.1.27",
+		"@quark-fw/plugin": "0.1.27",
 		"@trpc/client": "~11.18.0",
 		"@types/react-dom": "^19.2.3",
 		"express": "^5.2.1",
@@ -36,8 +36,8 @@
 		"@mantine/dates": "^9.0.0",
 		"@mantine/modals": "^9.0.0",
 		"@mantine/notifications": "^9.0.0",
-		"@quark-fw/core": "0.1.26",
-		"@quark-fw/store": "0.1.26",
+		"@quark-fw/core": "0.1.27",
+		"@quark-fw/store": "0.1.27",
 		"@vitejs/plugin-react": "^5.1.0",
 		"react": "^19.2.4",
 		"react-dom": "^19.2.4",

package/src/frontend/App.tsx

@@ -1,3 +1,7 @@
+// объявление виртуального модуля vite: import его дать не может, поэтому
+// reference path — и правило про него выключено осознанно
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="./vite-virtual.d.ts" />
 import "vite/modulepreload-polyfill";
 // ВСЕ стили Mantine — только layered-варианты. Смешение layered ядра с
 // не-layered пакетами меняет приоритеты правил, и в прод-сборке (где CSS

package/src/frontend/displayError.ts

@@ -7,10 +7,16 @@ import { errorMessage, setErrorHandler } from "@quark-fw/store/src/errors.js";
 if (typeof window !== "undefined") {
 	setErrorHandler((error, context) => {
 		console.error(context ? `[${context}]` : "[quark]", error);
+		// requestId приходит в data ошибки tRPC (errorFormatter плагина):
+		// по нему строки этого запроса находятся в логах сервера
+		const requestId = (error as { data?: { requestId?: string } })?.data
+			?.requestId;
 		notifications.show({
 			color: "red",
 			title: context ?? "Ошибка",
-			message: errorMessage(error),
+			message: requestId
+				? `${errorMessage(error)} · id ${requestId.slice(0, 8)}`
+				: errorMessage(error),
 		});
 	});
 }

package/src/frontend/vite-virtual.d.ts

@@ -0,0 +1,5 @@
+// Виртуальные модули Vite: резолвятся плагином vite:modulepreload-polyfill,
+// на диске их нет, и TypeScript 7 (проверяет side-effect импорты) без
+// объявления не находит модуль. Файл подключается reference path из
+// App.tsx — так он попадает и в программы приложений.
+declare module "vite/modulepreload-polyfill";

package/src/index.ts

@@ -7,7 +7,13 @@ import getRenderMiddleware from "./ssr/getRenderMiddleware.js";
 import { getVite } from "./utils/vite.js";
 import { appFrontendRoot, buildPaths } from "./utils/viteConfig.js";
 import { httpRouter, preRouter } from "@quark-fw/plugin/http.js";
+import { requestContextMiddleware } from "./requestContextMiddleware.js";
+import { securityHeadersMiddleware } from "./securityHeadersMiddleware.js";
+import { parseTrustProxy } from "./utils/parseTrustProxy.js";
 import {} from "@quark-fw/plugin-react/src/global.js";
+import { log as rootLog } from "@quark-fw/core/src/log.js";
+
+const log = rootLog.child({ scope: "react" });
 
 const isProd = process.env.NODE_ENV === "production";
 
@@ -31,11 +37,15 @@ await quark.registerPlugin({
 
 		// за обратным прокси (TLS-терминация) нужно доверять X-Forwarded-*,
 		// иначе req.secure всегда false и secure-cookie не выставляются.
-		// Включается явно: TRUST_PROXY=1 (или список адресов).
-		if (process.env.TRUST_PROXY) {
-			app.set("trust proxy", process.env.TRUST_PROXY);
-		}
+		// Включается явно: TRUST_PROXY=1 (число хопов) или список адресов.
+		const trustProxy = parseTrustProxy(process.env.TRUST_PROXY);
+		if (trustProxy !== undefined) app.set("trust proxy", trustProxy);
 
+		// request id и контекст запроса — раньше всего остального, чтобы
+		// каждая строка лога любого middleware была привязана к запросу
+		app.use(requestContextMiddleware);
+		app.disable("x-powered-by");
+		app.use(securityHeadersMiddleware);
 		// сквозные middleware (сессии, passport) — раньше всех обработчиков
 		app.use(preRouter);
 		// маршруты плагинов (например /api/trpc) — до статики и SSR
@@ -76,9 +86,10 @@ await quark.registerPlugin({
 
 		const listen = (port: number) => {
 			server = app.listen(port, () => {
-				console.log(
-					`[react] ${isProd ? "production" : "dev"} http://localhost:${port}`,
-				);
+				log.info("listening", {
+					mode: isProd ? "production" : "dev",
+					url: `http://localhost:${port}`,
+				});
 			});
 		};
 
@@ -99,8 +110,16 @@ await quark.registerPlugin({
 	async onDestroy() {
 		unsubscribePort?.();
 		unsubscribePort = undefined;
-		server?.close();
+		const current = server;
 		server = undefined;
+		if (current) {
+			// close() ждёт только активные запросы, а keep-alive соединения
+			// без запроса держали бы процесс до таймаута shutdown в core
+			await new Promise<void>((resolve) => {
+				current.close(() => resolve());
+				current.closeIdleConnections();
+			});
+		}
 		await vite?.close();
 		vite = undefined;
 	},

package/src/requestContextMiddleware.test.ts

@@ -0,0 +1,52 @@
+import { afterAll, beforeAll, expect, test } from "vitest";
+import express from "express";
+import type { Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { getRequestContext } from "@quark-fw/core/src/requestContext.js";
+import { requestContextMiddleware } from "./requestContextMiddleware.js";
+
+let server: Server;
+let base: string;
+
+beforeAll(async () => {
+	const app = express();
+	app.use(requestContextMiddleware);
+	// контекст виден и после await — так его читают процедуры и логгер
+	app.get("/ctx", async (_req, res) => {
+		await new Promise((r) => setTimeout(r, 1));
+		res.json({ requestId: getRequestContext()?.requestId ?? null });
+	});
+	await new Promise<void>((resolve) => {
+		server = app.listen(0, () => resolve());
+	});
+	base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+});
+
+afterAll(() => {
+	server.close();
+});
+
+test("без заголовка: генерируется uuid, он же в ответе и в контексте", async () => {
+	const r = await fetch(`${base}/ctx`);
+	const header = r.headers.get("x-request-id");
+	expect(header).toMatch(/^[0-9a-f-]{36}$/);
+	expect(await r.json()).toEqual({ requestId: header });
+});
+
+test("безопасный входящий X-Request-Id сохраняется", async () => {
+	const r = await fetch(`${base}/ctx`, {
+		headers: { "x-request-id": "proxy-42.a_b" },
+	});
+	expect(r.headers.get("x-request-id")).toBe("proxy-42.a_b");
+	expect(await r.json()).toEqual({ requestId: "proxy-42.a_b" });
+});
+
+test("входящий id с посторонними символами или длиннее 128 заменяется", async () => {
+	for (const bad of ["a b", "<script>", "a".repeat(129)]) {
+		const r = await fetch(`${base}/ctx`, {
+			headers: { "x-request-id": bad },
+		});
+		expect(r.headers.get("x-request-id")).not.toBe(bad);
+		expect(r.headers.get("x-request-id")).toMatch(/^[0-9a-f-]{36}$/);
+	}
+});

package/src/requestContextMiddleware.ts

@@ -0,0 +1,41 @@
+import crypto from "node:crypto";
+import type { RequestHandler } from "express";
+import { runWithRequestContext } from "@quark-fw/core/src/requestContext.js";
+import { log as rootLog } from "@quark-fw/core/src/log.js";
+
+const log = rootLog.child({ scope: "http" });
+
+const HEADER = "x-request-id";
+// id от прокси попадает в логи и в ответ — принимаем только безопасную форму
+const SAFE_ID = /^[A-Za-z0-9._-]{1,128}$/;
+
+/**
+ * Открывает контекст запроса: request id (входящий X-Request-Id от прокси
+ * или новый uuid) доступен логгеру через AsyncLocalStorage во всём, что
+ * выполняется внутри запроса — middleware, процедурах tRPC, SSR. Тот же id
+ * возвращается заголовком ответа, чтобы по жалобе пользователя найти строки.
+ *
+ * По завершении пишется строка доступа: метод, путь, статус, время.
+ * Хешированные ассеты не пишутся — это шум без пользы.
+ */
+export const requestContextMiddleware: RequestHandler = (req, res, next) => {
+	const incoming = req.headers[HEADER];
+	const requestId =
+		typeof incoming === "string" && SAFE_ID.test(incoming)
+			? incoming
+			: crypto.randomUUID();
+	res.setHeader(HEADER, requestId);
+
+	const started = performance.now();
+	res.on("finish", () => {
+		if (req.path.startsWith("/assets/")) return;
+		log.info("request", {
+			method: req.method,
+			path: req.originalUrl,
+			status: res.statusCode,
+			ms: Math.round(performance.now() - started),
+		});
+	});
+
+	runWithRequestContext({ requestId }, next);
+};

package/src/securityHeadersMiddleware.test.ts

@@ -0,0 +1,45 @@
+import { afterAll, beforeAll, expect, test } from "vitest";
+import express from "express";
+import type { Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { securityHeadersMiddleware } from "./securityHeadersMiddleware.js";
+
+let server: Server;
+let base: string;
+
+beforeAll(async () => {
+	const app = express();
+	// как в проде за Traefik: один доверенный хоп, протокол из заголовка
+	app.set("trust proxy", 1);
+	app.disable("x-powered-by");
+	app.use(securityHeadersMiddleware);
+	app.get("/", (_req, res) => res.send("ok"));
+	await new Promise<void>((resolve) => {
+		server = app.listen(0, () => resolve());
+	});
+	base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+});
+
+afterAll(() => {
+	server.close();
+});
+
+test("http: базовые заголовки есть, HSTS и X-Powered-By нет", async () => {
+	const r = await fetch(base + "/");
+	expect(r.headers.get("x-content-type-options")).toBe("nosniff");
+	expect(r.headers.get("x-frame-options")).toBe("SAMEORIGIN");
+	expect(r.headers.get("referrer-policy")).toBe(
+		"strict-origin-when-cross-origin",
+	);
+	expect(r.headers.get("strict-transport-security")).toBeNull();
+	expect(r.headers.get("x-powered-by")).toBeNull();
+});
+
+test("https за доверенным прокси: добавляется HSTS", async () => {
+	const r = await fetch(base + "/", {
+		headers: { "x-forwarded-proto": "https" },
+	});
+	expect(r.headers.get("strict-transport-security")).toBe(
+		"max-age=15552000; includeSubDomains",
+	);
+});

package/src/securityHeadersMiddleware.ts

@@ -0,0 +1,26 @@
+import type { RequestHandler } from "express";
+
+/**
+ * Базовые заголовки безопасности. Без helmet: нужных заголовков четыре, а
+ * зависимость тянула бы дефолты, которые здесь не подходят (CSP, COOP).
+ *
+ * HSTS ставится только на https-ответ: req.secure за прокси работает через
+ * TRUST_PROXY, а на голом http заголовок браузеры игнорируют и он лишь
+ * мешает локальной отладке.
+ *
+ * CSP намеренно нет: SSR пишет инлайн-скрипты (window.cache в стриме,
+ * ColorSchemeScript Mantine), для неё нужен per-request nonce через стрим и
+ * renderToPipeableStream — отдельная задача.
+ */
+export const securityHeadersMiddleware: RequestHandler = (req, res, next) => {
+	res.setHeader("X-Content-Type-Options", "nosniff");
+	res.setHeader("X-Frame-Options", "SAMEORIGIN");
+	res.setHeader("Referrer-Policy", "strict-origin-when-cross-origin");
+	if (req.secure) {
+		res.setHeader(
+			"Strict-Transport-Security",
+			"max-age=15552000; includeSubDomains",
+		);
+	}
+	next();
+};

package/src/ssr/createRequestTrpcClient.ts

@@ -1,6 +1,10 @@
 import { createTRPCClient, httpLink, unstable_localLink } from "@trpc/client";
 import type { Request, Response } from "express";
 import { jsonSafeFetch, type TRPCClient } from "@quark-fw/store";
+import { getRequestContext } from "@quark-fw/core/src/requestContext.js";
+import { log as rootLog } from "@quark-fw/core/src/log.js";
+
+const log = rootLog.child({ scope: "react" });
 
 // Тип роутера берём из сигнатуры link'а: plugin-react не зависит от
 // @trpc/server и не должен тянуть его ради одного типа
@@ -47,6 +51,9 @@ export function createRequestTrpcClient({
 	url,
 }: CreateRequestTrpcClientArgs): TRPCClient {
 	const cookie = req.headers.cookie;
+	// тот же request id, что у SSR-запроса: по HTTP он уходит заголовком,
+	// и логи API-процесса связываются с логами рендера
+	const requestId = getRequestContext()?.requestId;
 
 	if (!url && router && createContext) {
 		return createTRPCClient({
@@ -58,7 +65,7 @@ export function createRequestTrpcClient({
 					// только то, что по HTTP было бы 500
 					onError: ({ error, path }) => {
 						if (error.code === "INTERNAL_SERVER_ERROR") {
-							console.error(`[react] ssr tRPC ${path}:`, error);
+							log.error("ssr tRPC failed", { path, err: error });
 						}
 					},
 				}),
@@ -70,7 +77,10 @@ export function createRequestTrpcClient({
 		links: [
 			httpLink({
 				url: url ?? `http://127.0.0.1:${port}/api/trpc`,
-				headers: cookie ? { cookie } : {},
+				headers: {
+					...(cookie ? { cookie } : {}),
+					...(requestId ? { "x-request-id": requestId } : {}),
+				},
 				fetch: jsonSafeFetch,
 			}),
 		],

package/src/ssr/getRenderMiddleware.ts

@@ -25,6 +25,9 @@ import { createPreloadTagWriter } from "./createPreloadTagWriter.js";
 import { createRequestTrpcClient } from "./createRequestTrpcClient.js";
 import { createStreamingStore } from "./createStreamingStore.js";
 import { stripTrailingSlash } from "../utils/stripTrailingSlash.js";
+import { log as rootLog } from "@quark-fw/core/src/log.js";
+
+const log = rootLog.child({ scope: "react" });
 
 export type GetRenderMiddlewareArgs = {
 	/** dev: модули грузятся через vite; в prod — из собранного бандла */
@@ -214,14 +217,14 @@ export default function getRenderMiddleware({ vite }: GetRenderMiddlewareArgs) {
 						stream.pipe(res);
 					},
 					onError: (error) => {
-						console.error(error);
+						log.error("ssr stream failed", { err: error });
 						res.end(serverErrorBody(error, "message"));
 					},
 					bootstrapModules,
 				},
 			});
 		} catch (e: unknown) {
-			console.error(e);
+			log.error("ssr failed", { err: e });
 			res.status(500).end(serverErrorBody(e, "stack"));
 		}
 	};

package/src/utils/parseTrustProxy.test.ts

@@ -0,0 +1,56 @@
+import { expect, test } from "vitest";
+import express from "express";
+import type { Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { parseTrustProxy } from "./parseTrustProxy.js";
+
+test("разбор значений TRUST_PROXY", () => {
+	expect(parseTrustProxy(undefined)).toBeUndefined();
+	expect(parseTrustProxy("")).toBeUndefined();
+	expect(parseTrustProxy("1")).toBe(1);
+	expect(parseTrustProxy(" 2 ")).toBe(2);
+	expect(parseTrustProxy("true")).toBe(true);
+	expect(parseTrustProxy("false")).toBe(false);
+	expect(parseTrustProxy("loopback, 10.0.0.0/8")).toBe(
+		"loopback, 10.0.0.0/8",
+	);
+});
+
+const withApp = async (
+	trust: ReturnType<typeof parseTrustProxy>,
+	fn: (base: string) => Promise<void>,
+) => {
+	const app = express();
+	if (trust !== undefined) app.set("trust proxy", trust);
+	app.get("/ip", (req, res) => res.json({ ip: req.ip }));
+	let server!: Server;
+	await new Promise<void>((resolve) => {
+		server = app.listen(0, () => resolve());
+	});
+	try {
+		await fn(`http://127.0.0.1:${(server.address() as AddressInfo).port}`);
+	} finally {
+		server.close();
+	}
+};
+
+const ipVia = async (base: string, forwarded?: string) => {
+	const r = await fetch(`${base}/ip`, {
+		headers: forwarded ? { "x-forwarded-for": forwarded } : {},
+	});
+	return ((await r.json()) as { ip: string }).ip;
+};
+
+test("TRUST_PROXY=1 — один хоп: req.ip берётся из X-Forwarded-For, цепочка не спуфится", async () => {
+	await withApp(parseTrustProxy("1"), async (base) => {
+		expect(await ipVia(base, "203.0.113.5")).toBe("203.0.113.5");
+		// клиент дописал свой заголовок перед прокси — верим только последнему
+		expect(await ipVia(base, "1.1.1.1, 203.0.113.5")).toBe("203.0.113.5");
+	});
+});
+
+test('строка "1" как раньше: заголовок игнорируется, req.ip — адрес сокета', async () => {
+	await withApp("1", async (base) => {
+		expect(await ipVia(base, "203.0.113.5")).toMatch(/127\.0\.0\.1$/);
+	});
+});

package/src/utils/parseTrustProxy.ts

@@ -0,0 +1,19 @@
+/**
+ * TRUST_PROXY → значение express `trust proxy`.
+ *
+ * Строка "1" как есть трактуется express как список адресов и парсится в
+ * IP 0.0.0.1: ни один прокси не доверенный, req.ip — адрес прокси, req.secure
+ * — false. Поэтому число — это число доверенных хопов (Coolify/Traefik: 1),
+ * "true" — доверять всем X-Forwarded-* (небезопасно: клиент сам подставит
+ * IP), остальное — список адресов/подсетей (`loopback, 10.0.0.0/8`).
+ */
+export function parseTrustProxy(
+	value: string | undefined,
+): boolean | number | string | undefined {
+	const trimmed = value?.trim();
+	if (!trimmed) return undefined;
+	if (trimmed === "true") return true;
+	if (trimmed === "false") return false;
+	if (/^\d+$/.test(trimmed)) return Number(trimmed);
+	return trimmed;
+}