@pyreon/url-state 0.11.0

package/lib/index.js

@@ -0,0 +1,195 @@
+import { effect, onCleanup, signal } from "@pyreon/reactivity";
+
+//#region src/url.ts
+const _isBrowser = typeof window !== "undefined";
+/** Read a search param from the current URL. Returns `null` if not present. */
+function getParam(key) {
+	if (!_isBrowser) return null;
+	return new URLSearchParams(window.location.search).get(key);
+}
+/**
+* Read all values for a repeated param (e.g. `?tags=a&tags=b`).
+* Returns an empty array if the param is not present.
+*/
+function getParamAll(key) {
+	if (!_isBrowser) return [];
+	return new URLSearchParams(window.location.search).getAll(key);
+}
+/** Module-level router reference. Set via `setUrlRouter()`. */
+let _router = null;
+/** Register a router to use for URL updates instead of the raw history API. */
+function setUrlRouter(router) {
+	_router = router;
+}
+/** Write one or more search params to the URL without a full navigation. */
+function setParams(entries, replace) {
+	if (!_isBrowser) return;
+	const params = new URLSearchParams(window.location.search);
+	for (const [key, value] of Object.entries(entries)) if (value === null) params.delete(key);
+	else params.set(key, value);
+	const search = params.toString();
+	const url = search ? `${window.location.pathname}?${search}` : window.location.pathname;
+	if (_router) {
+		_router.replace(url);
+		return;
+	}
+	if (replace) history.replaceState(null, "", url);
+	else history.pushState(null, "", url);
+}
+/**
+* Write an array param using repeated keys (e.g. `?tags=a&tags=b`).
+* When `values` is null the param is deleted.
+*/
+function setParamRepeated(key, values, replace) {
+	if (!_isBrowser) return;
+	const params = new URLSearchParams(window.location.search);
+	params.delete(key);
+	if (values !== null) for (const v of values) params.append(key, v);
+	const search = params.toString();
+	const url = search ? `${window.location.pathname}?${search}` : window.location.pathname;
+	if (_router) {
+		_router.replace(url);
+		return;
+	}
+	if (replace) history.replaceState(null, "", url);
+	else history.pushState(null, "", url);
+}
+
+//#endregion
+//#region src/serializers.ts
+/** Infer a serializer pair from the type of the default value. */
+function inferSerializer(defaultValue, arrayFormat = "comma") {
+	if (Array.isArray(defaultValue)) {
+		if (arrayFormat === "repeat") return {
+			serialize: (v) => v.join("\0REPEAT\0"),
+			deserialize: (raw) => raw === "" ? [] : raw.split("\0REPEAT\0")
+		};
+		return {
+			serialize: (v) => v.join(","),
+			deserialize: (raw) => raw === "" ? [] : raw.split(",")
+		};
+	}
+	switch (typeof defaultValue) {
+		case "number": return {
+			serialize: (v) => String(v),
+			deserialize: (raw) => Number(raw)
+		};
+		case "boolean": return {
+			serialize: (v) => String(v),
+			deserialize: (raw) => raw === "true"
+		};
+		case "string": return {
+			serialize: (v) => v,
+			deserialize: (raw) => raw
+		};
+		case "object": return {
+			serialize: (v) => JSON.stringify(v),
+			deserialize: (raw) => JSON.parse(raw)
+		};
+		default: return {
+			serialize: (v) => String(v),
+			deserialize: (raw) => raw
+		};
+	}
+}
+
+//#endregion
+//#region src/use-url-state.ts
+function useUrlState(keyOrSchema, defaultOrOptions, maybeOptions) {
+	if (typeof keyOrSchema === "object") {
+		const schema = keyOrSchema;
+		const opts = defaultOrOptions;
+		const result = {};
+		for (const key of Object.keys(schema)) result[key] = createUrlSignal(key, schema[key], opts);
+		return result;
+	}
+	return createUrlSignal(keyOrSchema, defaultOrOptions, maybeOptions);
+}
+function createUrlSignal(key, defaultValue, options) {
+	const replace = options?.replace !== false;
+	const debounceMs = options?.debounce ?? 0;
+	const arrayFormat = options?.arrayFormat ?? "comma";
+	const isRepeat = Array.isArray(defaultValue) && arrayFormat === "repeat";
+	const { serialize, deserialize } = options?.serialize && options?.deserialize ? {
+		serialize: options.serialize,
+		deserialize: options.deserialize
+	} : inferSerializer(defaultValue, arrayFormat);
+	let initial;
+	if (isRepeat) {
+		const values = getParamAll(key);
+		initial = values.length > 0 ? values : defaultValue;
+	} else {
+		const raw = getParam(key);
+		initial = raw !== null ? deserialize(raw) : defaultValue;
+	}
+	const state = signal(initial);
+	let timer;
+	const writeUrl = (value) => {
+		if (isRepeat) {
+			const arr = value;
+			const defaultArr = defaultValue;
+			if (arr.length === defaultArr.length && arr.every((v, i) => v === defaultArr[i])) setParamRepeated(key, null, replace);
+			else setParamRepeated(key, arr, replace);
+			return;
+		}
+		const serialized = serialize(value);
+		if (serialized === serialize(defaultValue)) setParams({ [key]: null }, replace);
+		else setParams({ [key]: serialized }, replace);
+	};
+	/** Force-remove the param from URL regardless of value. */
+	const removeFromUrl = () => {
+		if (isRepeat) setParamRepeated(key, null, replace);
+		else setParams({ [key]: null }, replace);
+	};
+	const scheduleWrite = (value) => {
+		if (debounceMs <= 0) {
+			writeUrl(value);
+			return;
+		}
+		if (timer !== void 0) clearTimeout(timer);
+		timer = setTimeout(() => {
+			timer = void 0;
+			writeUrl(value);
+		}, debounceMs);
+	};
+	if (_isBrowser) {
+		const onPopState = () => {
+			let value;
+			if (isRepeat) {
+				const values = getParamAll(key);
+				value = values.length > 0 ? values : defaultValue;
+			} else {
+				const current = getParam(key);
+				value = current !== null ? deserialize(current) : defaultValue;
+			}
+			state.set(value);
+			options?.onChange?.(value);
+		};
+		effect(() => {
+			window.addEventListener("popstate", onPopState);
+			onCleanup(() => {
+				window.removeEventListener("popstate", onPopState);
+				if (timer !== void 0) clearTimeout(timer);
+			});
+		});
+	}
+	const accessor = (() => state());
+	accessor.set = (value) => {
+		state.set(value);
+		scheduleWrite(value);
+	};
+	accessor.reset = () => {
+		state.set(defaultValue);
+		scheduleWrite(defaultValue);
+	};
+	accessor.remove = () => {
+		state.set(defaultValue);
+		if (timer !== void 0) clearTimeout(timer);
+		removeFromUrl();
+	};
+	return accessor;
+}
+
+//#endregion
+export { setUrlRouter, useUrlState };
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/url.ts","../src/serializers.ts","../src/use-url-state.ts"],"sourcesContent":["const _isBrowser = typeof window !== \"undefined\"\n\n/** Read a search param from the current URL. Returns `null` if not present. */\nexport function getParam(key: string): string | null {\n  if (!_isBrowser) return null\n  return new URLSearchParams(window.location.search).get(key)\n}\n\n/**\n * Read all values for a repeated param (e.g. `?tags=a&tags=b`).\n * Returns an empty array if the param is not present.\n */\nexport function getParamAll(key: string): string[] {\n  if (!_isBrowser) return []\n  return new URLSearchParams(window.location.search).getAll(key)\n}\n\n/**\n * Minimal router-like interface — only the `replace` method is needed.\n * This avoids a hard dependency on `@pyreon/router`.\n */\nexport interface UrlRouter {\n  replace(path: string): void | Promise<void>\n}\n\n/** Module-level router reference. Set via `setUrlRouter()`. */\nlet _router: UrlRouter | null = null\n\n/** Register a router to use for URL updates instead of the raw history API. */\nexport function setUrlRouter(router: UrlRouter | null): void {\n  _router = router\n}\n\n/** @internal */\nexport function getUrlRouter(): UrlRouter | null {\n  return _router\n}\n\n/** Write one or more search params to the URL without a full navigation. */\nexport function setParams(entries: Record<string, string | null>, replace: boolean): void {\n  if (!_isBrowser) return\n\n  const params = new URLSearchParams(window.location.search)\n\n  for (const [key, value] of Object.entries(entries)) {\n    if (value === null) {\n      params.delete(key)\n    } else {\n      params.set(key, value)\n    }\n  }\n\n  const search = params.toString()\n  const url = search ? `${window.location.pathname}?${search}` : window.location.pathname\n\n  if (_router) {\n    _router.replace(url)\n    return\n  }\n\n  if (replace) {\n    history.replaceState(null, \"\", url)\n  } else {\n    history.pushState(null, \"\", url)\n  }\n}\n\n/**\n * Write an array param using repeated keys (e.g. `?tags=a&tags=b`).\n * When `values` is null the param is deleted.\n */\nexport function setParamRepeated(key: string, values: string[] | null, replace: boolean): void {\n  if (!_isBrowser) return\n\n  const params = new URLSearchParams(window.location.search)\n  params.delete(key)\n\n  if (values !== null) {\n    for (const v of values) {\n      params.append(key, v)\n    }\n  }\n\n  const search = params.toString()\n  const url = search ? `${window.location.pathname}?${search}` : window.location.pathname\n\n  if (_router) {\n    _router.replace(url)\n    return\n  }\n\n  if (replace) {\n    history.replaceState(null, \"\", url)\n  } else {\n    history.pushState(null, \"\", url)\n  }\n}\n\nexport { _isBrowser }\n","import type { ArrayFormat, Serializer } from \"./types\"\n\n/** Infer a serializer pair from the type of the default value. */\nexport function inferSerializer<T>(\n  defaultValue: T,\n  arrayFormat: ArrayFormat = \"comma\",\n): Serializer<T> {\n  if (Array.isArray(defaultValue)) {\n    if (arrayFormat === \"repeat\") {\n      return {\n        serialize: (v: T) => (v as string[]).join(\"\\0REPEAT\\0\"),\n        deserialize: (raw: string) => (raw === \"\" ? [] : raw.split(\"\\0REPEAT\\0\")) as T,\n      }\n    }\n    // comma (default)\n    return {\n      serialize: (v: T) => (v as string[]).join(\",\"),\n      deserialize: (raw: string) => (raw === \"\" ? [] : raw.split(\",\")) as T,\n    }\n  }\n\n  switch (typeof defaultValue) {\n    case \"number\":\n      return {\n        serialize: (v: T) => String(v),\n        deserialize: (raw: string) => Number(raw) as T,\n      }\n    case \"boolean\":\n      return {\n        serialize: (v: T) => String(v),\n        deserialize: (raw: string) => (raw === \"true\") as T,\n      }\n    case \"string\":\n      return {\n        serialize: (v: T) => v as string,\n        deserialize: (raw: string) => raw as T,\n      }\n    case \"object\":\n      return {\n        serialize: (v: T) => JSON.stringify(v),\n        deserialize: (raw: string) => JSON.parse(raw) as T,\n      }\n    default:\n      return {\n        serialize: (v: T) => String(v),\n        deserialize: (raw: string) => raw as T,\n      }\n  }\n}\n","import { effect, onCleanup, signal } from \"@pyreon/reactivity\"\nimport { inferSerializer } from \"./serializers\"\nimport type { Serializer, UrlStateOptions, UrlStateSignal } from \"./types\"\nimport { _isBrowser, getParam, getParamAll, setParamRepeated, setParams } from \"./url\"\n\n// ─── Single-param overload ──────────────────────────────────────────────────\n\n/**\n * Bind a single URL search parameter to a reactive signal.\n *\n * @example\n * ```ts\n * const page = useUrlState(\"page\", 1)\n * page()        // read reactively (number)\n * page.set(2)   // updates signal + URL\n * page.reset()  // back to 1\n * page.remove() // removes ?page entirely\n * ```\n */\nexport function useUrlState<T>(\n  key: string,\n  defaultValue: T,\n  options?: UrlStateOptions<T>,\n): UrlStateSignal<T>\n\n// ─── Schema overload ────────────────────────────────────────────────────────\n\n/**\n * Bind multiple URL search parameters at once via a schema object.\n *\n * @example\n * ```ts\n * const { page, q } = useUrlState({ page: 1, q: \"\" })\n * page()       // number\n * q.set(\"hi\") // updates ?q=hi\n * ```\n */\nexport function useUrlState<T extends Record<string, unknown>>(\n  schema: T,\n  options?: UrlStateOptions,\n): { [K in keyof T]: UrlStateSignal<T[K]> }\n\n// ─── Implementation ─────────────────────────────────────────────────────────\n\nexport function useUrlState<T>(\n  keyOrSchema: string | Record<string, unknown>,\n  defaultOrOptions?: T | UrlStateOptions,\n  maybeOptions?: UrlStateOptions<T>,\n): UrlStateSignal<T> | Record<string, UrlStateSignal<unknown>> {\n  // Schema mode\n  if (typeof keyOrSchema === \"object\") {\n    const schema = keyOrSchema as Record<string, unknown>\n    const opts = defaultOrOptions as UrlStateOptions | undefined\n    const result: Record<string, UrlStateSignal<unknown>> = {}\n\n    for (const key of Object.keys(schema)) {\n      result[key] = createUrlSignal(key, schema[key], opts)\n    }\n\n    return result\n  }\n\n  // Single-param mode\n  const key = keyOrSchema\n  const defaultValue = defaultOrOptions as T\n  const options = maybeOptions\n  return createUrlSignal(key, defaultValue, options)\n}\n\n// ─── Core factory ───────────────────────────────────────────────────────────\n\nfunction createUrlSignal<T>(\n  key: string,\n  defaultValue: T,\n  options?: UrlStateOptions<T>,\n): UrlStateSignal<T> {\n  const replace = options?.replace !== false\n  const debounceMs = options?.debounce ?? 0\n  const arrayFormat = options?.arrayFormat ?? \"comma\"\n  const isArray = Array.isArray(defaultValue)\n  const isRepeat = isArray && arrayFormat === \"repeat\"\n\n  const { serialize, deserialize }: Serializer<T> =\n    options?.serialize && options?.deserialize\n      ? { serialize: options.serialize, deserialize: options.deserialize }\n      : inferSerializer(defaultValue, arrayFormat)\n\n  // Read initial value from URL (falls back to default when missing or in SSR)\n  let initial: T\n  if (isRepeat) {\n    const values = getParamAll(key)\n    initial = values.length > 0 ? (values as T) : defaultValue\n  } else {\n    const raw = getParam(key)\n    initial = raw !== null ? deserialize(raw) : defaultValue\n  }\n\n  const state = signal<T>(initial)\n\n  // Pending debounce timer\n  let timer: ReturnType<typeof setTimeout> | undefined\n\n  // Write URL when signal changes\n  const writeUrl = (value: T) => {\n    if (isRepeat) {\n      const arr = value as string[]\n      const defaultArr = defaultValue as string[]\n      // Remove param when value equals default to keep URLs clean\n      if (arr.length === defaultArr.length && arr.every((v, i) => v === defaultArr[i])) {\n        setParamRepeated(key, null, replace)\n      } else {\n        setParamRepeated(key, arr, replace)\n      }\n      return\n    }\n\n    const serialized = serialize(value)\n    const defaultSerialized = serialize(defaultValue)\n\n    // Remove param when value equals default to keep URLs clean\n    if (serialized === defaultSerialized) {\n      setParams({ [key]: null }, replace)\n    } else {\n      setParams({ [key]: serialized }, replace)\n    }\n  }\n\n  /** Force-remove the param from URL regardless of value. */\n  const removeFromUrl = () => {\n    if (isRepeat) {\n      setParamRepeated(key, null, replace)\n    } else {\n      setParams({ [key]: null }, replace)\n    }\n  }\n\n  const scheduleWrite = (value: T) => {\n    if (debounceMs <= 0) {\n      writeUrl(value)\n      return\n    }\n    if (timer !== undefined) clearTimeout(timer)\n    timer = setTimeout(() => {\n      timer = undefined\n      writeUrl(value)\n    }, debounceMs)\n  }\n\n  // Listen for popstate (back/forward navigation)\n  if (_isBrowser) {\n    const onPopState = () => {\n      let value: T\n      if (isRepeat) {\n        const values = getParamAll(key)\n        value = values.length > 0 ? (values as T) : defaultValue\n      } else {\n        const current = getParam(key)\n        value = current !== null ? deserialize(current) : defaultValue\n      }\n      state.set(value)\n      options?.onChange?.(value)\n    }\n\n    effect(() => {\n      window.addEventListener(\"popstate\", onPopState)\n      onCleanup(() => {\n        window.removeEventListener(\"popstate\", onPopState)\n        if (timer !== undefined) clearTimeout(timer)\n      })\n    })\n  }\n\n  // Build the signal-like accessor\n  const accessor = (() => state()) as UrlStateSignal<T>\n\n  accessor.set = (value: T) => {\n    state.set(value)\n    scheduleWrite(value)\n  }\n\n  accessor.reset = () => {\n    state.set(defaultValue)\n    scheduleWrite(defaultValue)\n  }\n\n  accessor.remove = () => {\n    state.set(defaultValue)\n    if (timer !== undefined) clearTimeout(timer)\n    removeFromUrl()\n  }\n\n  return accessor\n}\n"],"mappings":"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"}

package/lib/types/index.d.ts

@@ -0,0 +1,88 @@
+//#region src/url.d.ts
+/**
+ * Minimal router-like interface — only the `replace` method is needed.
+ * This avoids a hard dependency on `@pyreon/router`.
+ */
+interface UrlRouter {
+  replace(path: string): void | Promise<void>;
+}
+/** Register a router to use for URL updates instead of the raw history API. */
+declare function setUrlRouter(router: UrlRouter | null): void;
+//#endregion
+//#region src/types.d.ts
+/** A signal-like accessor for a single URL search parameter. */
+interface UrlStateSignal<T> {
+  /** Read the current value reactively. */
+  (): T;
+  /** Write a new value and update the URL. */
+  set(value: T): void;
+  /** Reset to the default value and update the URL. */
+  reset(): void;
+  /** Remove the parameter from the URL entirely and reset signal to default. */
+  remove(): void;
+}
+/** Encoding strategy for array values in the URL. */
+type ArrayFormat = /** Comma-separated: `?tags=a,b` */"comma" /** Repeated keys: `?tags=a&tags=b` */ | "repeat";
+/** Options for `useUrlState`. */
+interface UrlStateOptions<T = unknown> {
+  /** Custom serializer — converts value to a URL-safe string. */
+  serialize?: (value: T) => string;
+  /** Custom deserializer — converts URL string back to a value. */
+  deserialize?: (raw: string) => T;
+  /**
+   * Use `history.replaceState` (true) or `history.pushState` (false).
+   * @default true
+   */
+  replace?: boolean;
+  /**
+   * Debounce URL writes by this many milliseconds.
+   * @default 0
+   */
+  debounce?: number;
+  /**
+   * Encoding strategy for array values.
+   * - `"comma"` — comma-separated: `?tags=a,b` (default)
+   * - `"repeat"` — repeated keys: `?tags=a&tags=b`
+   * @default "comma"
+   */
+  arrayFormat?: ArrayFormat;
+  /**
+   * Called when the URL param changes externally (popstate or another
+   * `useUrlState` call updating the same param).
+   */
+  onChange?: (value: T) => void;
+}
+/** Serializer pair for a given type. */
+interface Serializer<T> {
+  serialize: (value: T) => string;
+  deserialize: (raw: string) => T;
+}
+//#endregion
+//#region src/use-url-state.d.ts
+/**
+ * Bind a single URL search parameter to a reactive signal.
+ *
+ * @example
+ * ```ts
+ * const page = useUrlState("page", 1)
+ * page()        // read reactively (number)
+ * page.set(2)   // updates signal + URL
+ * page.reset()  // back to 1
+ * page.remove() // removes ?page entirely
+ * ```
+ */
+declare function useUrlState<T>(key: string, defaultValue: T, options?: UrlStateOptions<T>): UrlStateSignal<T>;
+/**
+ * Bind multiple URL search parameters at once via a schema object.
+ *
+ * @example
+ * ```ts
+ * const { page, q } = useUrlState({ page: 1, q: "" })
+ * page()       // number
+ * q.set("hi") // updates ?q=hi
+ * ```
+ */
+declare function useUrlState<T extends Record<string, unknown>>(schema: T, options?: UrlStateOptions): { [K in keyof T]: UrlStateSignal<T[K]> };
+//#endregion
+export { type ArrayFormat, type Serializer, type UrlRouter, type UrlStateOptions, type UrlStateSignal, setUrlRouter, useUrlState };
+//# sourceMappingURL=index2.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/url.ts","../../../src/types.ts","../../../src/use-url-state.ts"],"mappings":";;;AA6BA;;UARiB,SAAA;EACf,OAAA,CAAQ,IAAA,kBAAsB,OAAA;AAAA;;iBAOhB,YAAA,CAAa,MAAA,EAAQ,SAAA;;;;UC5BpB,cAAA;EDoBS;EAAA,IClBpB,CAAA;EDmBiC;ECjBrC,GAAA,CAAI,KAAA,EAAO,CAAA;EDiBH;ECfR,KAAA;EDeqC;ECbrC,MAAA;AAAA;;KAIU,WAAA;;UAOK,eAAA;EAnBc;EAqB7B,SAAA,IAAa,KAAA,EAAO,CAAA;EAjBR;EAmBZ,WAAA,IAAe,GAAA,aAAgB,CAAA;EArB3B;;;;EA0BJ,OAAA;EApBA;;;AAIF;EAqBE,QAAA;;;;AAdF;;;EAqBE,WAAA,GAAc,WAAA;EAjBiB;;;;EAsB/B,QAAA,IAAY,KAAA,EAAO,CAAA;AAAA;;UAIJ,UAAA;EACf,SAAA,GAAY,KAAA,EAAO,CAAA;EACnB,WAAA,GAAc,GAAA,aAAgB,CAAA;AAAA;;;AD/BhC;;;;;;;;;AAQA;;;AARA,iBEFgB,WAAA,GAAA,CACd,GAAA,UACA,YAAA,EAAc,CAAA,EACd,OAAA,GAAU,eAAA,CAAgB,CAAA,IACzB,cAAA,CAAe,CAAA;;;;;ADtBlB;;;;;;iBCoCgB,WAAA,WAAsB,MAAA,kBAAA,CACpC,MAAA,EAAQ,CAAA,EACR,OAAA,GAAU,eAAA,iBACK,CAAA,GAAI,cAAA,CAAe,CAAA,CAAE,CAAA"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@pyreon/url-state",
+  "version": "0.11.0",
+  "description": "Reactive URL search-param state for Pyreon — signal-backed, type-coerced, SSR-safe",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pyreon/pyreon.git",
+    "directory": "packages/fundamentals/url-state"
+  },
+  "homepage": "https://github.com/pyreon/fundamentals/tree/main/packages/url-state#readme",
+  "bugs": {
+    "url": "https://github.com/pyreon/pyreon/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./lib/index.js",
+      "types": "./lib/types/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "vl_rolldown_build",
+    "dev": "vl_rolldown_build-watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check ."
+  },
+  "peerDependencies": {
+    "@pyreon/reactivity": "^0.11.0"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.8.3",
+    "@pyreon/reactivity": "^0.11.0",
+    "@vitus-labs/tools-lint": "^1.11.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @pyreon/url-state — Reactive URL search-param state for Pyreon.
+ *
+ * Signal-backed, type-coerced, SSR-safe URL state management. Each search
+ * parameter is a reactive signal that syncs with the browser URL.
+ *
+ * @example
+ * ```ts
+ * import { useUrlState } from '@pyreon/url-state'
+ *
+ * // Single parameter — type inferred from default
+ * const page = useUrlState('page', 1)
+ * page()        // read reactively (number)
+ * page.set(2)   // updates signal + URL (?page=2)
+ * page.reset()  // back to default (removes ?page)
+ * page.remove() // removes ?page entirely
+ *
+ * // Schema mode — multiple params at once
+ * const { q, sort } = useUrlState({ q: '', sort: 'name' })
+ * q.set('hello')  // ?q=hello&sort=name
+ *
+ * // Array with repeated keys
+ * const tags = useUrlState('tags', [] as string[], { arrayFormat: 'repeat' })
+ * tags.set(['a', 'b'])  // ?tags=a&tags=b
+ *
+ * // Router integration — uses router.replace() when available
+ * import { setUrlRouter } from '@pyreon/url-state'
+ * setUrlRouter(router)  // pass your @pyreon/router instance
+ * ```
+ */
+
+export { setUrlRouter } from "./url"
+export { useUrlState } from "./use-url-state"
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type { ArrayFormat, Serializer, UrlStateOptions, UrlStateSignal } from "./types"
+export type { UrlRouter } from "./url"

package/src/serializers.ts

@@ -0,0 +1,49 @@
+import type { ArrayFormat, Serializer } from "./types"
+
+/** Infer a serializer pair from the type of the default value. */
+export function inferSerializer<T>(
+  defaultValue: T,
+  arrayFormat: ArrayFormat = "comma",
+): Serializer<T> {
+  if (Array.isArray(defaultValue)) {
+    if (arrayFormat === "repeat") {
+      return {
+        serialize: (v: T) => (v as string[]).join("\0REPEAT\0"),
+        deserialize: (raw: string) => (raw === "" ? [] : raw.split("\0REPEAT\0")) as T,
+      }
+    }
+    // comma (default)
+    return {
+      serialize: (v: T) => (v as string[]).join(","),
+      deserialize: (raw: string) => (raw === "" ? [] : raw.split(",")) as T,
+    }
+  }
+
+  switch (typeof defaultValue) {
+    case "number":
+      return {
+        serialize: (v: T) => String(v),
+        deserialize: (raw: string) => Number(raw) as T,
+      }
+    case "boolean":
+      return {
+        serialize: (v: T) => String(v),
+        deserialize: (raw: string) => (raw === "true") as T,
+      }
+    case "string":
+      return {
+        serialize: (v: T) => v as string,
+        deserialize: (raw: string) => raw as T,
+      }
+    case "object":
+      return {
+        serialize: (v: T) => JSON.stringify(v),
+        deserialize: (raw: string) => JSON.parse(raw) as T,
+      }
+    default:
+      return {
+        serialize: (v: T) => String(v),
+        deserialize: (raw: string) => raw as T,
+      }
+  }
+}