@cfasim-ui/shared 0.4.11 → 0.4.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/shared",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "type": "module",
   "description": "Shared utilities for cfasim-ui",
   "license": "Apache-2.0",

package/src/index.ts

@@ -22,5 +22,10 @@ export {
   deserialize,
   paramsToQuery,
   queryToParams,
+  jsonCodec,
+} from "./useUrlParams.js";
+export type {
+  UrlParamsOptions,
+  ParamCodec,
+  ParamCodecs,
 } from "./useUrlParams.js";
-export type { UrlParamsOptions } from "./useUrlParams.js";

package/src/useUrlParams.test.ts

@@ -7,6 +7,7 @@ import {
   paramsToQuery,
   queryToParams,
   useUrlParams,
+  jsonCodec,
   type UrlParamsRouter,
   type UrlParamsRoute,
 } from "./useUrlParams.js";
@@ -92,6 +93,105 @@ describe("queryToParams", () => {
   });
 });
 
+type InfectionRate =
+  | { type: "constant"; value: number; duration: number }
+  | { type: "empirical"; points: [number, number][] };
+
+describe("paramsToQuery (with codecs)", () => {
+  it("treats a codec path as a single atomic URL key", () => {
+    const defaults: { rate: InfectionRate } = {
+      rate: { type: "constant", value: 0.5, duration: 3 },
+    };
+    const params: { rate: InfectionRate } = {
+      rate: {
+        type: "empirical",
+        points: [
+          [0, 0],
+          [2, 1],
+        ],
+      },
+    };
+    expect(paramsToQuery(params, defaults, { rate: jsonCodec })).toEqual({
+      rate: JSON.stringify(params.rate),
+    });
+  });
+
+  it("omits a codec value that stringifies equal to the default", () => {
+    const defaults = { rate: { type: "constant", value: 0.5 } };
+    const params = { rate: { type: "constant", value: 0.5 } };
+    expect(paramsToQuery(params, defaults, { rate: jsonCodec })).toEqual({});
+  });
+
+  it("emits codec keys alongside ordinary leaves", () => {
+    const defaults = {
+      population: 10_000,
+      rate: { type: "constant", value: 0.5 } as { type: string; value: number },
+    };
+    const params = {
+      population: 20_000,
+      rate: { type: "constant", value: 0.5 } as { type: string; value: number },
+    };
+    expect(paramsToQuery(params, defaults, { rate: jsonCodec })).toEqual({
+      population: "20000",
+      // rate matches → omitted
+    });
+  });
+});
+
+describe("queryToParams (with codecs)", () => {
+  it("decodes a codec value through its custom deserializer", () => {
+    const defaults: { rate: InfectionRate } = {
+      rate: { type: "constant", value: 0.5, duration: 3 },
+    };
+    const variant: InfectionRate = {
+      type: "empirical",
+      points: [
+        [0, 0],
+        [2, 1],
+      ],
+    };
+    expect(
+      queryToParams({ rate: JSON.stringify(variant) }, defaults, {
+        rate: jsonCodec,
+      }),
+    ).toEqual({ rate: variant });
+  });
+
+  it("drops URL keys nested inside a codec boundary", () => {
+    const defaults: { rate: InfectionRate } = {
+      rate: { type: "constant", value: 0.5, duration: 3 },
+    };
+    // Stale leaf keys from the constant variant should not punch through
+    // the codec value.
+    expect(
+      queryToParams({ "rate.value": "0.9", "rate.duration": "7" }, defaults, {
+        rate: jsonCodec,
+      }),
+    ).toEqual({});
+  });
+
+  it("swallows malformed codec payloads instead of throwing", () => {
+    const defaults = { rate: { type: "constant", value: 0.5 } };
+    expect(
+      queryToParams({ rate: "{not-valid-json" }, defaults, { rate: jsonCodec }),
+    ).toEqual({});
+  });
+
+  it("supports a custom codec (base-N encoded number)", () => {
+    const hexCodec = {
+      serialize: (v: unknown) => Number(v).toString(16),
+      deserialize: (raw: string) => Number.parseInt(raw, 16),
+    };
+    const defaults = { n: 0 };
+    expect(queryToParams({ n: "ff" }, defaults, { n: hexCodec })).toEqual({
+      n: 255,
+    });
+    expect(paramsToQuery({ n: 255 }, defaults, { n: hexCodec })).toEqual({
+      n: "ff",
+    });
+  });
+});
+
 function makeRouterStub(initialQuery: Record<string, unknown> = {}) {
   const route = reactive<UrlParamsRoute>({ query: { ...initialQuery } });
   const replace = vi.fn(({ query }: { query: Record<string, string> }) => {
@@ -312,6 +412,247 @@ describe("useUrlParams (composable)", () => {
     });
   });
 
+  describe("nested params", () => {
+    it("hydrates a nested leaf from a dotted query key", async () => {
+      const { router, route } = makeRouterStub({ "nested.foo": "9" });
+      const params = reactive({ a: 1, nested: { foo: 5, bar: 10 } });
+      mountWith(() =>
+        useUrlParams(
+          params,
+          { a: 1, nested: { foo: 5, bar: 10 } },
+          { router, route, debounceMs: 0 },
+        ),
+      );
+      await nextTick();
+      expect(params.a).toBe(1);
+      expect(params.nested).toEqual({ foo: 9, bar: 10 });
+    });
+
+    it("writes only changed nested leaves with dotted keys", async () => {
+      const { router, route } = makeRouterStub();
+      const params = reactive({ a: 1, nested: { foo: 5, bar: 10 } });
+      mountWith(() =>
+        useUrlParams(
+          params,
+          { a: 1, nested: { foo: 5, bar: 10 } },
+          { router, route, debounceMs: 0 },
+        ),
+      );
+      await nextTick();
+      params.nested.foo = 7;
+      await nextTick();
+      await new Promise((r) => setTimeout(r, 5));
+      expect(route.query).toEqual({ "nested.foo": "7" });
+    });
+
+    it("round-trips a deeply nested structure", async () => {
+      const { router, route } = makeRouterStub({
+        "deep.a.b.c": "42",
+        "deep.flag": "true",
+      });
+      const defaults = { deep: { a: { b: { c: 0 } }, flag: false } };
+      const params = reactive(structuredClone(defaults));
+      mountWith(() =>
+        useUrlParams(params, defaults, { router, route, debounceMs: 0 }),
+      );
+      await nextTick();
+      expect(params.deep.a.b.c).toBe(42);
+      expect(params.deep.flag).toBe(true);
+    });
+
+    it("preserves sibling leaves when an override updates one branch", async () => {
+      const { router, route } = makeRouterStub({ "nested.foo": "99" });
+      const params = reactive({ nested: { foo: 1, bar: 2, baz: 3 } });
+      mountWith(() =>
+        useUrlParams(
+          params,
+          { nested: { foo: 1, bar: 2, baz: 3 } },
+          { router, route, debounceMs: 0 },
+        ),
+      );
+      await nextTick();
+      expect(params.nested).toEqual({ foo: 99, bar: 2, baz: 3 });
+    });
+
+    it("drops dotted keys that have no matching default leaf", async () => {
+      const defaults = { nested: { foo: 1 } };
+      expect(
+        queryToParams({ "nested.unknown": "5", "nested.foo": "9" }, defaults),
+      ).toEqual({ nested: { foo: 9 } });
+    });
+
+    it("paramsToQuery emits only nested leaves that differ", () => {
+      const defaults = { a: 1, nested: { foo: 5, bar: 10 } };
+      expect(
+        paramsToQuery({ a: 1, nested: { foo: 7, bar: 10 } }, defaults),
+      ).toEqual({ "nested.foo": "7" });
+    });
+
+    it("include with a parent path covers all descendants", async () => {
+      const { router, route } = makeRouterStub();
+      const params = reactive({ a: 1, nested: { foo: 5, bar: 10 } });
+      mountWith(() =>
+        useUrlParams(
+          params,
+          { a: 1, nested: { foo: 5, bar: 10 } },
+          { router, route, debounceMs: 0, include: ["nested"] },
+        ),
+      );
+      await nextTick();
+      params.a = 99;
+      params.nested.foo = 7;
+      params.nested.bar = 11;
+      await nextTick();
+      await new Promise((r) => setTimeout(r, 5));
+      expect(route.query).toEqual({ "nested.foo": "7", "nested.bar": "11" });
+    });
+
+    it("ignore with a dotted path skips a single leaf", async () => {
+      const { router, route } = makeRouterStub();
+      const params = reactive({ nested: { foo: 5, bar: 10 } });
+      mountWith(() =>
+        useUrlParams(
+          params,
+          { nested: { foo: 5, bar: 10 } },
+          { router, route, debounceMs: 0, ignore: ["nested.bar"] },
+        ),
+      );
+      await nextTick();
+      params.nested.foo = 7;
+      params.nested.bar = 11;
+      await nextTick();
+      await new Promise((r) => setTimeout(r, 5));
+      expect(route.query).toEqual({ "nested.foo": "7" });
+    });
+
+    it("URI-encodes segments so keys containing dots round-trip", () => {
+      const defaults = { "weird.key": 1, nested: { "a.b": 2 } };
+      const params = { "weird.key": 5, nested: { "a.b": 7 } };
+      const query = paramsToQuery(params, defaults);
+      expect(query).toEqual({
+        "weird%2Ekey": "5",
+        "nested.a%2Eb": "7",
+      });
+      expect(queryToParams(query, defaults)).toEqual({
+        "weird.key": 5,
+        nested: { "a.b": 7 },
+      });
+    });
+
+    it("flattens an array of objects into indexed dotted paths", () => {
+      const defaults = {
+        items: [
+          { name: "a", value: 1 },
+          { name: "b", value: 2 },
+        ],
+      };
+      const params = {
+        items: [
+          { name: "a", value: 1 },
+          { name: "b", value: 99 },
+        ],
+      };
+      expect(paramsToQuery(params, defaults)).toEqual({
+        "items.1.value": "99",
+      });
+    });
+
+    it("rebuilds array-shaped defaults from indexed dotted keys", () => {
+      const defaults = {
+        items: [
+          { name: "a", value: 1 },
+          { name: "b", value: 2 },
+        ],
+      };
+      expect(queryToParams({ "items.0.value": "5" }, defaults)).toEqual({
+        items: [{ value: 5 }],
+      });
+    });
+
+    it("array of arrays recurses with numeric indices, inner arrays stay leaves", () => {
+      const defaults = {
+        matrix: [
+          [1, 2],
+          [3, 4],
+        ],
+      };
+      const params = {
+        matrix: [
+          [1, 2],
+          [9, 9],
+        ],
+      };
+      expect(paramsToQuery(params, defaults)).toEqual({
+        "matrix.1": "9,9",
+      });
+      expect(queryToParams({ "matrix.0": "7,8" }, defaults)).toEqual({
+        matrix: [[7, 8]],
+      });
+    });
+
+    it("URL override on a leaf array replaces it wholesale (does not merge element-wise)", async () => {
+      const { router, route } = makeRouterStub({ "matrix.0": "7" });
+      const defaults = {
+        matrix: [
+          [1, 2],
+          [3, 4],
+        ],
+      };
+      const params = reactive(structuredClone(defaults));
+      mountWith(() =>
+        useUrlParams(params, defaults, { router, route, debounceMs: 0 }),
+      );
+      await nextTick();
+      expect(params.matrix).toEqual([[7], [3, 4]]);
+    });
+
+    it("array-of-primitives still round-trips as a comma-joined leaf", () => {
+      const defaults = { tags: [1, 2, 3] };
+      expect(paramsToQuery({ tags: [4, 5, 6] }, defaults)).toEqual({
+        tags: "4,5,6",
+      });
+      expect(queryToParams({ tags: "4,5,6" }, defaults)).toEqual({
+        tags: [4, 5, 6],
+      });
+    });
+
+    it("updates one element of an array-of-objects via the URL while preserving siblings", async () => {
+      const { router, route } = makeRouterStub({ "items.1.value": "99" });
+      const defaults = {
+        items: [
+          { name: "a", value: 1 },
+          { name: "b", value: 2 },
+        ],
+      };
+      const params = reactive(structuredClone(defaults));
+      mountWith(() =>
+        useUrlParams(params, defaults, { router, route, debounceMs: 0 }),
+      );
+      await nextTick();
+      expect(params.items).toEqual([
+        { name: "a", value: 1 },
+        { name: "b", value: 99 },
+      ]);
+    });
+
+    it("reset restores nested defaults", async () => {
+      const { router, route } = makeRouterStub({ "nested.foo": "9" });
+      const params = reactive({ nested: { foo: 1, bar: 2 } });
+      const { api } = mountWith(() =>
+        useUrlParams(
+          params,
+          { nested: { foo: 1, bar: 2 } },
+          { router, route, debounceMs: 0 },
+        ),
+      );
+      await nextTick();
+      expect(params.nested.foo).toBe(9);
+      api.reset();
+      await nextTick();
+      expect(params.nested).toEqual({ foo: 1, bar: 2 });
+    });
+  });
+
   describe("defaults variants", () => {
     it("accepts a Ref as defaults", async () => {
       const { router, route } = makeRouterStub({ a: "7" });
@@ -358,4 +699,118 @@ describe("useUrlParams (composable)", () => {
       expect(params.a).toBe(0);
     });
   });
+
+  describe("codecs", () => {
+    it("round-trips a tagged-union field through a single URL key", async () => {
+      const { router, route } = makeRouterStub();
+      const defaults: { rate: InfectionRate; population: number } = {
+        rate: { type: "constant", value: 0.5, duration: 3 },
+        population: 10_000,
+      };
+      const params = reactive(structuredClone(defaults));
+      mountWith(() =>
+        useUrlParams(params, defaults, {
+          router,
+          route,
+          debounceMs: 0,
+          codecs: { rate: jsonCodec },
+        }),
+      );
+      await nextTick();
+      params.rate = {
+        type: "empirical",
+        points: [
+          [0, 0],
+          [2, 1],
+          [4, 1.2],
+        ],
+      };
+      await nextTick();
+      await new Promise((r) => setTimeout(r, 5));
+      expect(route.query).toEqual({ rate: JSON.stringify(params.rate) });
+    });
+
+    it("hydrates a codec-encoded variant from the URL", async () => {
+      const variant: InfectionRate = {
+        type: "empirical",
+        points: [
+          [0, 0],
+          [2, 1],
+        ],
+      };
+      const { router, route } = makeRouterStub({
+        rate: JSON.stringify(variant),
+      });
+      const defaults: { rate: InfectionRate } = {
+        rate: { type: "constant", value: 0.5, duration: 3 },
+      };
+      const params = reactive(structuredClone(defaults));
+      mountWith(() =>
+        useUrlParams(params, defaults, {
+          router,
+          route,
+          debounceMs: 0,
+          codecs: { rate: jsonCodec },
+        }),
+      );
+      await nextTick();
+      expect(params.rate).toEqual(variant);
+    });
+
+    it("ignores stale descendant URL keys at a codec path", async () => {
+      // Pretend an older version stored `rate.value=0.9`; with a codec at
+      // `rate` we must not punch that through into the variant.
+      const { router, route } = makeRouterStub({ "rate.value": "0.9" });
+      const defaults: { rate: InfectionRate } = {
+        rate: { type: "constant", value: 0.5, duration: 3 },
+      };
+      const params = reactive(structuredClone(defaults));
+      mountWith(() =>
+        useUrlParams(params, defaults, {
+          router,
+          route,
+          debounceMs: 0,
+          codecs: { rate: jsonCodec },
+        }),
+      );
+      await nextTick();
+      expect(params.rate).toEqual({
+        type: "constant",
+        value: 0.5,
+        duration: 3,
+      });
+    });
+
+    it("reset clears a codec value from the URL", async () => {
+      const variant: InfectionRate = {
+        type: "empirical",
+        points: [[0, 1]],
+      };
+      const { router, route } = makeRouterStub({
+        rate: JSON.stringify(variant),
+      });
+      const defaults: { rate: InfectionRate } = {
+        rate: { type: "constant", value: 0.5, duration: 3 },
+      };
+      const params = reactive(structuredClone(defaults));
+      const { api } = mountWith(() =>
+        useUrlParams(params, defaults, {
+          router,
+          route,
+          debounceMs: 0,
+          codecs: { rate: jsonCodec },
+        }),
+      );
+      await nextTick();
+      expect(params.rate).toEqual(variant);
+      api.reset();
+      await nextTick();
+      expect(params.rate).toEqual({
+        type: "constant",
+        value: 0.5,
+        duration: 3,
+      });
+      expect(route.query).toEqual({});
+    });
+  });
 });

package/src/useUrlParams.ts

@@ -28,6 +28,50 @@ export interface UrlParamsRoute {
  */
 export type DefaultsInput<T> = T | Ref<T> | (() => T | undefined);
 
+/**
+ * A path into the params object. Either a top-level key (autocompleted from
+ * `T`) or a dotted path to a nested leaf (`"nested.foo"`). Matches the leaf
+ * exactly or any descendant when used as `include`/`ignore`.
+ */
+export type ParamPath<T> = keyof T | (string & {});
+
+/**
+ * Custom serializer/deserializer pair for a single path. Lets the consumer
+ * round-trip a value through one URL key as an opaque string instead of
+ * letting `useUrlParams` flatten through it. Use for tagged unions,
+ * polymorphic objects, or anything else whose shape can change at runtime —
+ * the default leaf-flattening can only enumerate fields present in
+ * `defaults`, so variants that aren't the default variant lose their
+ * fields.
+ */
+export type ParamCodec = {
+  serialize: (value: unknown) => string;
+  deserialize: (raw: string) => unknown;
+};
+
+/**
+ * Map of dotted path → codec. A path with a codec is treated as a single
+ * atomic leaf: its whole subtree round-trips through one URL key, and any
+ * descendant URL keys are ignored. Top-level keys (`"infectionRate"`) and
+ * nested paths (`"model.infectionRate"`) both work; segments in the path
+ * use `.` as the separator, matching the same convention as
+ * `include`/`ignore`.
+ */
+export type ParamCodecs = Record<string, ParamCodec>;
+
+/**
+ * Convenience codec that uses `JSON.stringify` / `JSON.parse`. Suitable
+ * for tagged unions and small object/array values. Note that comparison
+ * during URL writes is string-equality on the stringified form, so two
+ * objects with the same fields in different key orders will look distinct;
+ * provide a custom codec with a normalized stringifier if you need
+ * order-insensitive comparison.
+ */
+export const jsonCodec: ParamCodec = {
+  serialize: (value) => JSON.stringify(value),
+  deserialize: (raw) => JSON.parse(raw),
+};
+
 export type UrlParamsOptions<T> = {
   debounceMs?: number;
   /**
@@ -39,14 +83,23 @@ export type UrlParamsOptions<T> = {
   router?: UrlParamsRouter;
   route?: UrlParamsRoute;
   /**
-   * Only sync these keys. Useful when `defaults` contains labels, flags, or
-   * other fields the user never edits.
+   * Only sync these paths. Accepts top-level keys or dotted paths to nested
+   * leaves; a parent path implicitly covers all of its descendants.
    */
-  include?: (keyof T)[];
+  include?: ParamPath<T>[];
   /**
-   * Sync all keys except these. Ignored if `include` is provided.
+   * Sync all paths except these. Same matching rules as `include`. Ignored
+   * if `include` is provided.
    */
-  ignore?: (keyof T)[];
+  ignore?: ParamPath<T>[];
+  /**
+   * Per-path codecs. A path listed here is round-tripped as one opaque
+   * string under that key (using the codec's `serialize`/`deserialize`)
+   * instead of being flattened. URL keys nested inside a codec path are
+   * ignored, so a leftover `foo.bar=1` from an earlier shape doesn't
+   * punch through the atomic value.
+   */
+  codecs?: ParamCodecs;
 };
 
 export type ResetOptions = {
@@ -74,16 +127,169 @@ export function deserialize(raw: string, defaultValue: unknown): unknown {
   return raw;
 }
 
+// A "container" is any non-null object — plain object or array. A "branch"
+// is a container we recurse into when flattening defaults: plain objects
+// always recurse; arrays only recurse when at least one element is itself a
+// plain object (so `[1, 2, 3]` stays a comma-joined leaf, while
+// `[{foo: 1}, {foo: 2}]` becomes `items.0.foo=…&items.1.foo=…`).
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isContainer(
+  value: unknown,
+): value is Record<string, unknown> | unknown[] {
+  return value !== null && typeof value === "object";
+}
+
+function isBranch(value: unknown): boolean {
+  if (isPlainObject(value)) return true;
+  // Recurse into arrays whose elements are themselves containers (plain
+  // objects or arrays), so array-of-arrays and array-of-objects map onto
+  // indexed dotted paths. Arrays of primitives stay as comma-joined leaves.
+  if (Array.isArray(value)) return value.some(isContainer);
+  return false;
+}
+
+function* flattenLeaves(
+  obj: Record<string, unknown> | unknown[],
+  prefix: string[] = [],
+  stopPaths?: Set<string>,
+): Generator<[string[], unknown]> {
+  const entries: Array<[string, unknown]> = Array.isArray(obj)
+    ? obj.map((v, i) => [String(i), v])
+    : Object.entries(obj);
+  for (const [k, v] of entries) {
+    const path = [...prefix, k];
+    // `stopPaths` (codec paths) halt recursion: the whole subtree at that
+    // path is yielded as a single leaf value so a codec can serialize it
+    // atomically.
+    if (isBranch(v) && !stopPaths?.has(path.join("."))) {
+      yield* flattenLeaves(
+        v as Record<string, unknown> | unknown[],
+        path,
+        stopPaths,
+      );
+    } else {
+      yield [path, v];
+    }
+  }
+}
+
+// True iff some proper-prefix ancestor of `segments` is a codec path. Used
+// to drop URL keys that would punch through a codec boundary (e.g. a stale
+// `infectionRate.value=0.5` left over from before infectionRate gained a
+// codec).
+function pathIsInsideAnyCodec(
+  segments: string[],
+  codecPaths: Set<string>,
+): boolean {
+  for (let i = 1; i < segments.length; i++) {
+    if (codecPaths.has(segments.slice(0, i).join("."))) return true;
+  }
+  return false;
+}
+
+function getAtSegments(obj: unknown, segments: string[]): unknown {
+  let cur: unknown = obj;
+  for (const p of segments) {
+    if (!isContainer(cur)) return undefined;
+    cur = (cur as Record<string, unknown>)[p];
+  }
+  return cur;
+}
+
+// Sets `value` at `segments` inside `obj`. When `defaults` is supplied,
+// missing intermediate slots match the defaults' shape (array vs object) at
+// the same path — so a URL like `items.0.foo=5` rebuilds an array, not an
+// object with numeric keys.
+function setAtSegments(
+  obj: Record<string, unknown> | unknown[],
+  segments: string[],
+  value: unknown,
+  defaults?: unknown,
+): void {
+  let cur: Record<string, unknown> | unknown[] = obj;
+  let defCur: unknown = defaults;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const p = segments[i];
+    const defNext = isContainer(defCur)
+      ? (defCur as Record<string, unknown>)[p]
+      : undefined;
+    const slot = (cur as Record<string, unknown>)[p];
+    if (!isContainer(slot)) {
+      (cur as Record<string, unknown>)[p] = Array.isArray(defNext) ? [] : {};
+    }
+    cur = (cur as Record<string, unknown>)[p] as
+      | Record<string, unknown>
+      | unknown[];
+    defCur = defNext;
+  }
+  (cur as Record<string, unknown>)[segments[segments.length - 1]] = value;
+}
+
+// Encode/decode segment arrays to/from URL query keys. Each segment is
+// percent-encoded so a literal `.` inside a key name won't collide with the
+// nesting separator. `encodeURIComponent` leaves `.` alone, so we replace
+// it manually to `%2E`. The encoded key still passes cleanly through
+// `URLSearchParams` and vue-router.
+function encodeKey(segments: string[]): string {
+  return segments
+    .map((s) => encodeURIComponent(s).replace(/\./g, "%2E"))
+    .join(".");
+}
+
+function decodeKey(key: string): string[] {
+  return key.split(".").map(decodeURIComponent);
+}
+
+// Recursive merge used to layer defaults onto the cloned current params.
+// Descends into matching containers (objects and arrays) so sibling
+// branches survive. URL overrides bypass this and use `setAtSegments`
+// directly, since a comma-encoded leaf array must replace its slot
+// wholesale rather than merge element-wise with the default.
+function deepMerge(
+  target: Record<string, unknown> | unknown[],
+  source: Record<string, unknown> | unknown[],
+  stopPaths?: Set<string>,
+  prefix: string[] = [],
+): Record<string, unknown> | unknown[] {
+  for (const [k, v] of Object.entries(source)) {
+    const slot = (target as Record<string, unknown>)[k];
+    const path = stopPaths ? [...prefix, k] : prefix;
+    const atStop = stopPaths?.has(path.join("."));
+    if (!atStop && isContainer(v) && isContainer(slot)) {
+      deepMerge(slot, v, stopPaths, path);
+    } else {
+      // Codec paths are atomic: overwrite the target subtree with source's
+      // value instead of merging the two variants field-by-field (which
+      // would produce a malformed hybrid for tagged unions).
+      (target as Record<string, unknown>)[k] = v;
+    }
+  }
+  return target;
+}
+
 export function paramsToQuery<T extends object>(
   params: T,
   defaults: T,
+  codecs?: ParamCodecs,
 ): Record<string, string> {
   const query: Record<string, string> = {};
-  for (const key of Object.keys(defaults) as (keyof T & string)[]) {
-    const serialized = serialize(params[key]);
-    const defaultSerialized = serialize(defaults[key]);
+  const stopPaths = codecs ? new Set(Object.keys(codecs)) : undefined;
+  for (const [segments, defaultLeaf] of flattenLeaves(
+    defaults as Record<string, unknown>,
+    [],
+    stopPaths,
+  )) {
+    const paramLeaf = getAtSegments(params, segments);
+    if (paramLeaf === undefined) continue;
+    const codec = codecs?.[segments.join(".")];
+    const serializeFn = codec ? codec.serialize : serialize;
+    const serialized = serializeFn(paramLeaf);
+    const defaultSerialized = serializeFn(defaultLeaf);
     if (serialized !== defaultSerialized) {
-      query[key] = serialized;
+      query[encodeKey(segments)] = serialized;
     }
   }
   return query;
@@ -92,13 +298,30 @@ export function paramsToQuery<T extends object>(
 export function queryToParams<T extends object>(
   query: Record<string, unknown>,
   defaults: T,
+  codecs?: ParamCodecs,
 ): Partial<T> {
   const result: Record<string, unknown> = {};
-  const defaultsRecord = defaults as Record<string, unknown>;
+  const codecPaths = codecs ? new Set(Object.keys(codecs)) : undefined;
   for (const [key, raw] of Object.entries(query)) {
-    if (!(key in defaultsRecord)) continue;
     if (typeof raw !== "string") continue;
-    result[key] = deserialize(raw, defaultsRecord[key]);
+    const segments = decodeKey(key);
+    const pathStr = segments.join(".");
+    const codec = codecs?.[pathStr];
+    if (codec) {
+      try {
+        setAtSegments(result, segments, codec.deserialize(raw), defaults);
+      } catch {
+        // Malformed codec value — skip rather than corrupt the params.
+      }
+      continue;
+    }
+    // Drop descendants of a codec path; the codec owns the whole subtree.
+    if (codecPaths && pathIsInsideAnyCodec(segments, codecPaths)) continue;
+    const defaultLeaf = getAtSegments(defaults, segments);
+    // Drop unknown dotted keys: matches the flat behavior and keeps the
+    // params shape stable.
+    if (defaultLeaf === undefined) continue;
+    setAtSegments(result, segments, deserialize(raw, defaultLeaf), defaults);
   }
   return result as Partial<T>;
 }
@@ -127,22 +350,43 @@ function toGetter<T>(input: DefaultsInput<T>): () => T | undefined {
   return () => input as T;
 }
 
-function filterKeys<T extends object>(
+// `include`/`ignore` entries are dotted strings using `.` as a JS-side path
+// separator (one segment per key). A path is in scope iff it (or any
+// ancestor) matches an include entry, or it (and all its ancestors) avoid
+// every ignore entry. `include` wins when both are supplied.
+function segmentsStartWith(path: string[], prefix: string[]): boolean {
+  if (prefix.length > path.length) return false;
+  for (let i = 0; i < prefix.length; i++) {
+    if (path[i] !== prefix[i]) return false;
+  }
+  return true;
+}
+
+function pathInScope(
+  path: string[],
+  include?: string[][],
+  ignore?: string[][],
+): boolean {
+  if (include) return include.some((entry) => segmentsStartWith(path, entry));
+  if (ignore) return !ignore.some((entry) => segmentsStartWith(path, entry));
+  return true;
+}
+
+function filterDefaults<T extends object>(
   obj: T,
-  include?: (keyof T)[],
-  ignore?: (keyof T)[],
+  include?: string[][],
+  ignore?: string[][],
+  stopPaths?: Set<string>,
 ): T {
   if (!include && !ignore) return obj;
-  const src = obj as Record<string, unknown>;
   const out: Record<string, unknown> = {};
-  for (const k of Object.keys(src)) {
-    const key = k as keyof T;
-    if (include) {
-      if (include.includes(key)) out[k] = src[k];
-    } else if (ignore) {
-      if (!ignore.includes(key)) out[k] = src[k];
-    } else {
-      out[k] = src[k];
+  for (const [path, leaf] of flattenLeaves(
+    obj as Record<string, unknown>,
+    [],
+    stopPaths,
+  )) {
+    if (pathInScope(path, include, ignore)) {
+      setAtSegments(out, path, leaf, obj);
     }
   }
   return out as T;
@@ -151,7 +395,8 @@ function filterKeys<T extends object>(
 /**
  * Syncs a reactive params object with the URL query string. Only values
  * that differ from defaults appear in the URL. Accepts either a `ref()`
- * or a `reactive()` object.
+ * or a `reactive()` object. Nested objects are encoded as dotted keys
+ * (`nested.foo=5`); arrays of primitives remain comma-joined leaves.
  *
  * For async defaults (e.g. loaded from WASM/network), pass a getter or ref
  * that returns `undefined` until ready, and call `hydrate()` once defaults
@@ -171,11 +416,16 @@ export function useUrlParams<T extends object>(
   options: UrlParamsOptions<T> = {},
 ) {
   const debounceMs = options.debounceMs ?? 300;
-  const { router, route, include, ignore } = options;
+  const { router, route, include, ignore, codecs } = options;
+  const includeSegments = include?.map((e) => String(e).split("."));
+  const ignoreSegments = ignore?.map((e) => String(e).split("."));
+  const codecPaths = codecs ? new Set(Object.keys(codecs)) : undefined;
   const getDefaults = toGetter<T>(defaults);
   const scopedDefaults = (): T | undefined => {
     const d = getDefaults();
-    return d === undefined ? undefined : filterKeys(d, include, ignore);
+    return d === undefined
+      ? undefined
+      : filterDefaults(d, includeSegments, ignoreSegments, codecPaths);
   };
 
   function readQuery(): Record<string, unknown> {
@@ -195,18 +445,24 @@ export function useUrlParams<T extends object>(
     return isRef(params) ? params.value : params;
   }
 
-  function apply(overrides: Partial<T>, d: T) {
+  function apply(overrides: Array<[string[], unknown]>, d: T) {
     // Layer order (later wins): current params -> defaults -> URL overrides.
     // Starting from current preserves keys outside the sync scope (i.e.
     // those filtered out by `include`/`ignore`), which matters when `params`
-    // is a ref and the whole object gets replaced below. `toRaw` unwraps
-    // reactive proxies so `structuredClone` doesn't choke.
-    const current = toRaw(read());
-    const merged = {
-      ...structuredClone(current),
-      ...structuredClone(toRaw(d)),
-      ...overrides,
-    } as T;
+    // is a ref and the whole object gets replaced below. Defaults deep-merge
+    // so sibling branches survive; URL overrides are applied at leaf
+    // precision so a leaf array like `tags=1,2` replaces the whole leaf
+    // instead of merging element-wise with the default array.
+    const current = structuredClone(toRaw(read())) as Record<string, unknown>;
+    deepMerge(
+      current,
+      structuredClone(toRaw(d)) as Record<string, unknown>,
+      codecPaths,
+    );
+    for (const [segments, value] of overrides) {
+      setAtSegments(current, segments, value, d);
+    }
+    const merged = current as T;
     if (isRef(params)) {
       params.value = merged;
     } else {
@@ -214,13 +470,36 @@ export function useUrlParams<T extends object>(
     }
   }
 
+  function readOverrides(d: T): Array<[string[], unknown]> {
+    const out: Array<[string[], unknown]> = [];
+    for (const [key, raw] of Object.entries(readQuery())) {
+      if (typeof raw !== "string") continue;
+      const segments = decodeKey(key);
+      const pathStr = segments.join(".");
+      const codec = codecs?.[pathStr];
+      if (codec) {
+        try {
+          out.push([segments, codec.deserialize(raw)]);
+        } catch {
+          // skip malformed codec values
+        }
+        continue;
+      }
+      if (codecPaths && pathIsInsideAnyCodec(segments, codecPaths)) continue;
+      const defaultLeaf = getAtSegments(d, segments);
+      if (defaultLeaf === undefined) continue;
+      out.push([segments, deserialize(raw, defaultLeaf)]);
+    }
+    return out;
+  }
+
   let hydrated = false;
 
   function hydrate(): boolean {
     const d = scopedDefaults();
     if (d === undefined) return false;
-    const overrides = queryToParams(readQuery(), d);
-    if (Object.keys(overrides).length > 0) apply(overrides, d);
+    const overrides = readOverrides(d);
+    if (overrides.length > 0) apply(overrides, d);
     hydrated = true;
     return true;
   }
@@ -232,8 +511,7 @@ export function useUrlParams<T extends object>(
     }
     const d = scopedDefaults();
     if (d === undefined) return;
-    const overrides = queryToParams(readQuery(), d);
-    apply(overrides, d);
+    apply(readOverrides(d), d);
   }
 
   onMounted(() => {
@@ -250,7 +528,7 @@ export function useUrlParams<T extends object>(
       debounceTimer = setTimeout(() => {
         const d = scopedDefaults();
         if (d === undefined) return;
-        writeQuery(paramsToQuery(read(), d));
+        writeQuery(paramsToQuery(read(), d, codecs));
       }, debounceMs);
     },
     { deep: true },
@@ -281,7 +559,7 @@ export function useUrlParams<T extends object>(
     const { clearUrl = true } = opts;
     const d = scopedDefaults();
     if (d === undefined) return;
-    apply({}, d);
+    apply([], d);
     if (clearUrl) {
       if (debounceTimer) clearTimeout(debounceTimer);
       writeQuery({});