@ai-matrx/kit 0.5.0

package/dist/toast.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/toast.ts"],"sourcesContent":["/**\n * @ai-matrx/kit/toast — the captured sonner wrapper, as a factory.\n *\n * A bare `toast.error(...)` from \"sonner\" is INVISIBLE to any error-capture\n * sink — every modern sonner call site silently bypasses error capture (the\n * exact hole matrx-frontend found in its marketing feature, 2026-07-20).\n * `createMatrxToast` returns a drop-in `toast` whose API is identical to the\n * one you pass in — `error` and `warning` additionally feed the injected\n * capture sink. A user seeing the failure is not evidence that it is minor,\n * so error toasts stay red unless a specific downgrade rule says otherwise.\n * Success/info/etc. pass straight through untouched.\n *\n * Ported from matrx-frontend `lib/toast.ts` with the two seams inverted:\n *\n * - `sonner` is NOT imported: the host passes its own `toast` object into the\n *   factory (`createMatrxToast({ toast })`). That removes the peer-resolution\n *   problem entirely — this module has zero dependencies — and the input is\n *   typed STRUCTURALLY (callable + `.error` + `.warning`) so the returned\n *   `toast` keeps the host's full sonner type, and no `.d.ts` in this package\n *   references \"sonner\". The `sonner` entry in `peerDependencies` is\n *   advisory-only (optional; nothing resolves it at runtime).\n * - `captureError` from the app's diagnostics store becomes the injected\n *   `capture?: (info) => void`. Omitted, capture is a no-op and every call\n *   forwards identically (the original's payload shape is preserved exactly:\n *   `source: \"user-toast\"`, the `[warning] ` prefix, the \"Error toast\"\n *   fallback, `raw: { kind, message?, data }`). A throwing `capture` never\n *   breaks the toast.\n *\n * Usage (once, in the host app):\n *   import { toast as sonnerToast } from \"sonner\";\n *   export const { toast, toastErrorAlreadyCaptured } =\n *     createMatrxToast({ toast: sonnerToast, capture: captureError });\n */\n\nimport type { ReactNode } from \"react\";\n\n/** What sonner accepts as a toast title (structural: sonner's `titleT`). */\nexport type ToastMessage = ReactNode | (() => ReactNode);\n\n/** Structural stand-in for sonner's `ExternalToast` options bag. */\nexport interface ToastData {\n  description?: unknown;\n  [key: string]: unknown;\n}\n\n/**\n * The structural surface this factory needs from the injected toast object:\n * callable, with `error` and `warning` methods. sonner's `toast` satisfies\n * this for every version this package targets. Deliberate typing choices so\n * the REAL sonner object is assignable without a cast under\n * `strictFunctionTypes`: the call signature uses `never[]` (accepts any\n * function — consumers call through their own `T`, never this signature),\n * and `error`/`warning` use METHOD syntax for bivariant parameter checks\n * against sonner's `ExternalToast`.\n */\nexport interface SonnerLikeToast {\n  (...args: never[]): string | number;\n  error(message: ToastMessage, data?: ToastData): string | number;\n  warning(message: ToastMessage, data?: ToastData): string | number;\n}\n\n/** The payload handed to the injected capture sink — the original's shape. */\nexport interface CapturedToastInfo {\n  source: \"user-toast\";\n  message: string;\n  userMessage: string;\n  raw: {\n    kind: \"error\" | \"warning\";\n    message: string | undefined;\n    data: ToastData | undefined;\n  };\n}\n\nexport interface CreateMatrxToastOptions<T extends SonnerLikeToast> {\n  /** The host's sonner `toast` object (or any structural equivalent). */\n  toast: T;\n  /**\n   * Error-capture sink fed by `.error` / `.warning`. Omitted: no-op.\n   * Must never be load-bearing — a throw here is swallowed.\n   */\n  capture?: (info: CapturedToastInfo) => void;\n}\n\nexport interface MatrxToast<T extends SonnerLikeToast> {\n  /** Drop-in replacement for the injected `toast`, with error/warning capture. */\n  toast: T;\n  /**\n   * Render an error toast when the originating failure was already captured\n   * at its canonical boundary. Only for aggregate/derived UI notices; the\n   * caller must be able to name the upstream capture seam.\n   */\n  toastErrorAlreadyCaptured: T[\"error\"];\n}\n\nfunction messageText(message: ToastMessage, data?: ToastData): string {\n  const description =\n    data && typeof data.description === \"string\" ? data.description : \"\";\n  const title = typeof message === \"string\" ? message : \"\";\n  return [title, description].filter(Boolean).join(\" — \") || \"Error toast\";\n}\n\n/** Build the captured toast pair around the host's sonner `toast` object. */\nexport function createMatrxToast<T extends SonnerLikeToast>({\n  toast: hostToast,\n  capture,\n}: CreateMatrxToastOptions<T>): MatrxToast<T> {\n  if (typeof hostToast !== \"function\") {\n    throw new Error(\n      \"createMatrxToast: options.toast must be the sonner `toast` object (or a structural equivalent) — got \" +\n        typeof hostToast,\n    );\n  }\n\n  function captureToast(\n    kind: \"error\" | \"warning\",\n    message: ToastMessage,\n    data?: ToastData,\n  ): void {\n    if (!capture) return;\n    try {\n      capture({\n        source: \"user-toast\",\n        message: `${kind === \"warning\" ? \"[warning] \" : \"\"}${messageText(message, data)}`,\n        userMessage: messageText(message, data),\n        raw: {\n          kind,\n          message: typeof message === \"string\" ? message : undefined,\n          data,\n        },\n      });\n    } catch {\n      /* capture must never break the toast */\n    }\n  }\n\n  const error: SonnerLikeToast[\"error\"] = (message, data) => {\n    captureToast(\"error\", message, data);\n    return hostToast.error(message, data);\n  };\n\n  const warning: SonnerLikeToast[\"warning\"] = (message, data) => {\n    captureToast(\"warning\", message, data);\n    return hostToast.warning(message, data);\n  };\n\n  // The constraint's call signature is `never[]` (see SonnerLikeToast), so\n  // forwarding the base call goes through a widened alias of the host object.\n  const forward = hostToast as unknown as (\n    ...args: Parameters<T>\n  ) => ReturnType<T>;\n  const toast: T = Object.assign(\n    ((...args: Parameters<T>) => forward(...args)) as unknown as T,\n    hostToast,\n    { error, warning },\n  );\n\n  const toastErrorAlreadyCaptured = ((\n    message: ToastMessage,\n    data?: ToastData,\n  ) => hostToast.error(message, data)) as unknown as T[\"error\"];\n\n  return { toast, toastErrorAlreadyCaptured };\n}\n"],"mappings":";;;AA8FA,SAAS,YAAY,SAAuB,MAA0B;AACpE,QAAM,cACJ,QAAQ,OAAO,KAAK,gBAAgB,WAAW,KAAK,cAAc;AACpE,QAAM,QAAQ,OAAO,YAAY,WAAW,UAAU;AACtD,SAAO,CAAC,OAAO,WAAW,EAAE,OAAO,OAAO,EAAE,KAAK,UAAK,KAAK;AAC7D;AAGO,SAAS,iBAA4C;AAAA,EAC1D,OAAO;AAAA,EACP;AACF,GAA8C;AAC5C,MAAI,OAAO,cAAc,YAAY;AACnC,UAAM,IAAI;AAAA,MACR,+GACE,OAAO;AAAA,IACX;AAAA,EACF;AAEA,WAAS,aACP,MACA,SACA,MACM;AACN,QAAI,CAAC,QAAS;AACd,QAAI;AACF,cAAQ;AAAA,QACN,QAAQ;AAAA,QACR,SAAS,GAAG,SAAS,YAAY,eAAe,EAAE,GAAG,YAAY,SAAS,IAAI,CAAC;AAAA,QAC/E,aAAa,YAAY,SAAS,IAAI;AAAA,QACtC,KAAK;AAAA,UACH;AAAA,UACA,SAAS,OAAO,YAAY,WAAW,UAAU;AAAA,UACjD;AAAA,QACF;AAAA,MACF,CAAC;AAAA,IACH,QAAQ;AAAA,IAER;AAAA,EACF;AAEA,QAAM,QAAkC,CAAC,SAAS,SAAS;AACzD,iBAAa,SAAS,SAAS,IAAI;AACnC,WAAO,UAAU,MAAM,SAAS,IAAI;AAAA,EACtC;AAEA,QAAM,UAAsC,CAAC,SAAS,SAAS;AAC7D,iBAAa,WAAW,SAAS,IAAI;AACrC,WAAO,UAAU,QAAQ,SAAS,IAAI;AAAA,EACxC;AAIA,QAAM,UAAU;AAGhB,QAAM,QAAW,OAAO;AAAA,KACrB,IAAI,SAAwB,QAAQ,GAAG,IAAI;AAAA,IAC5C;AAAA,IACA,EAAE,OAAO,QAAQ;AAAA,EACnB;AAEA,QAAM,6BAA6B,CACjC,SACA,SACG,UAAU,MAAM,SAAS,IAAI;AAElC,SAAO,EAAE,OAAO,0BAA0B;AAC5C;","names":[]}

package/dist/url-state.cjs

@@ -0,0 +1,212 @@
+"use client";
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/url-state.ts
+var url_state_exports = {};
+__export(url_state_exports, {
+  booleanUrlCodec: () => booleanUrlCodec,
+  commitUrlParams: () => commitUrlParams,
+  enumUrlCodec: () => enumUrlCodec,
+  historyModeForParamChange: () => historyModeForParamChange,
+  jsonUrlCodec: () => jsonUrlCodec,
+  positiveIntegerUrlCodec: () => positiveIntegerUrlCodec,
+  setUrlStateRouter: () => setUrlStateRouter,
+  stringUrlCodec: () => stringUrlCodec,
+  useMirroredUrlState: () => useMirroredUrlState,
+  useUrlSearchParams: () => useUrlSearchParams,
+  useUrlState: () => useUrlState
+});
+module.exports = __toCommonJS(url_state_exports);
+var import_react = require("react");
+var URL_STATE_EVENT = "matrx:url-state";
+var ROUTER_SLOT = /* @__PURE__ */ Symbol.for("ai-matrx.kit.url-state-router");
+function getRouter() {
+  return globalThis[ROUTER_SLOT] ?? null;
+}
+function setUrlStateRouter(router) {
+  globalThis[ROUTER_SLOT] = router;
+}
+function currentLocation() {
+  const custom = getRouter()?.getLocation;
+  if (custom) return custom();
+  return {
+    pathname: window.location.pathname,
+    search: window.location.search,
+    hash: window.location.hash
+  };
+}
+function subscribeToUrl(listener) {
+  window.addEventListener("popstate", listener);
+  window.addEventListener(URL_STATE_EVENT, listener);
+  return () => {
+    window.removeEventListener("popstate", listener);
+    window.removeEventListener(URL_STATE_EVENT, listener);
+  };
+}
+function getUrlSnapshot() {
+  return currentLocation().search;
+}
+function getServerUrlSnapshot() {
+  return "";
+}
+function useUrlSearchParams() {
+  const search = (0, import_react.useSyncExternalStore)(
+    subscribeToUrl,
+    getUrlSnapshot,
+    getServerUrlSnapshot
+  );
+  return (0, import_react.useMemo)(() => new URLSearchParams(search), [search]);
+}
+function commitUrlParams(patch, history) {
+  const location = currentLocation();
+  const params = new URLSearchParams(location.search);
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null || value === "") params.delete(key);
+    else params.set(key, value);
+  }
+  const query = params.toString();
+  const next = `${location.pathname}${query ? `?${query}` : ""}${location.hash}`;
+  const current = `${location.pathname}${location.search}${location.hash}`;
+  if (next === current) return;
+  const router = getRouter();
+  if (router) {
+    if (history === "replace") router.replace(next);
+    else router.push(next);
+  } else if (history === "replace") {
+    window.history.replaceState(window.history.state, "", next);
+  } else {
+    window.history.pushState(window.history.state, "", next);
+  }
+  window.dispatchEvent(new Event(URL_STATE_EVENT));
+}
+function historyModeForParamChange(current, next, textKeys) {
+  const keys = /* @__PURE__ */ new Set([...current.keys(), ...next.keys()]);
+  const changed = [...keys].filter(
+    (key) => current.get(key) !== next.get(key)
+  );
+  if (changed.length === 0) return "replace";
+  return changed.every((key) => textKeys.includes(key)) ? "replace" : "push";
+}
+function useUrlState(key, codec) {
+  const searchParams = useUrlSearchParams();
+  const value = codec.parse(searchParams.get(key));
+  const setValue = (next, options) => {
+    commitUrlParams(
+      { [key]: codec.serialize(next) },
+      options?.history ?? "push"
+    );
+  };
+  return [value, setValue];
+}
+function stringUrlCodec(defaultValue = "") {
+  return {
+    defaultValue,
+    parse: (raw) => raw ?? defaultValue,
+    serialize: (value) => value === defaultValue ? null : value
+  };
+}
+function enumUrlCodec(values, defaultValue) {
+  const allowed = new Set(values);
+  return {
+    defaultValue,
+    parse: (raw) => raw && allowed.has(raw) ? raw : defaultValue,
+    serialize: (value) => value === defaultValue ? null : value
+  };
+}
+function booleanUrlCodec(defaultValue = false) {
+  return {
+    defaultValue,
+    parse: (raw) => raw === null ? defaultValue : raw === "1",
+    serialize: (value) => value === defaultValue ? null : value ? "1" : "0"
+  };
+}
+function positiveIntegerUrlCodec(defaultValue) {
+  return {
+    defaultValue,
+    parse: (raw) => {
+      const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;
+      return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultValue;
+    },
+    serialize: (value) => value === defaultValue || !Number.isFinite(value) || value <= 0 ? null : String(Math.trunc(value))
+  };
+}
+function jsonUrlCodec(defaultValue, isValid) {
+  return {
+    defaultValue,
+    parse: (raw) => {
+      if (!raw) return defaultValue;
+      try {
+        const parsed = JSON.parse(raw);
+        return isValid(parsed) ? parsed : defaultValue;
+      } catch {
+        return defaultValue;
+      }
+    },
+    serialize: (value) => JSON.stringify(value) === JSON.stringify(defaultValue) ? null : JSON.stringify(value)
+  };
+}
+function useMirroredUrlState(options) {
+  const { parse, toParams, isSame, textKeys = [], resetKey } = options;
+  const params = useUrlSearchParams();
+  const optionsRef = (0, import_react.useRef)(options);
+  optionsRef.current = options;
+  const [value, setValue] = (0, import_react.useState)(
+    () => parse(
+      typeof window === "undefined" ? new URLSearchParams() : new URLSearchParams(currentLocation().search)
+    )
+  );
+  (0, import_react.useEffect)(() => {
+    if (typeof window === "undefined") return;
+    const current = new URLSearchParams(currentLocation().search);
+    const patch = optionsRef.current.toParams(value);
+    const next = new URLSearchParams(current);
+    for (const [key, v] of Object.entries(patch)) {
+      if (v === null || v === "") next.delete(key);
+      else next.set(key, v);
+    }
+    if (next.toString() === current.toString()) return;
+    commitUrlParams(patch, historyModeForParamChange(current, next, textKeys));
+  }, [value]);
+  (0, import_react.useEffect)(() => {
+    const fromUrl = optionsRef.current.parse(
+      new URLSearchParams(currentLocation().search)
+    );
+    setValue((prev) => optionsRef.current.isSame(prev, fromUrl) ? prev : fromUrl);
+  }, [params]);
+  const previousResetKey = (0, import_react.useRef)(resetKey);
+  (0, import_react.useEffect)(() => {
+    const previous = previousResetKey.current;
+    previousResetKey.current = resetKey;
+    if (previous === resetKey) return;
+    if (previous === void 0 || previous === "") return;
+    if (resetKey === void 0 || resetKey === "") return;
+    const cleared = optionsRef.current.parse(new URLSearchParams());
+    setValue(cleared);
+    commitUrlParams(optionsRef.current.toParams(cleared), "replace");
+  }, [resetKey]);
+  const update = (0, import_react.useCallback)((updater) => {
+    setValue(
+      (prev) => typeof updater === "function" ? updater(prev) : updater
+    );
+  }, []);
+  return [value, update];
+}
+//# sourceMappingURL=url-state.cjs.map

package/dist/url-state.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/url-state.ts"],"sourcesContent":["\"use client\";\n\n/**\n * @ai-matrx/kit/url-state — THE canonical URL-state core. Every surface that\n * puts view state in the address bar goes through here.\n *\n * The URL is the source of truth: refresh, copied links, and browser\n * back/forward all reproduce the same value. Discrete controls push a history\n * entry by default; high-frequency text inputs opt into `replace` so a single\n * search does not create one entry per keystroke.\n *\n * WHY A RAW `history.pushState` IS A BUG, not just a style choice. It fires no\n * event and no popstate, so every OTHER url-backed control on the page keeps\n * rendering stale values until something unrelated re-renders it.\n * `commitUrlParams` dispatches `matrx:url-state`, which is what\n * `useUrlSearchParams` subscribes to. (Measured in the Matrx frontend,\n * 2026-08-25: 33 hand-rolled writes across 21 files, every one of them\n * silent.)\n *\n * PICK THE RIGHT ONE:\n *   one control owns one parameter       → `useUrlState` + a codec\n *   a cluster of values moving together  → `useMirroredUrlState`\n *\n * Codecs below cover string / enum / boolean / positive-integer / JSON, and all\n * of them OMIT the default rather than writing it, so a pristine surface has a\n * clean URL and a link carries only what the user actually chose.\n *\n * Ported verbatim from matrx-frontend `lib/url-state/useUrlState.ts`. The\n * original deliberately imports NOTHING from `next/navigation` — it writes\n * through the History API and notifies subscribers itself, which is exactly\n * how it runs in the Next.js App Router host. This port adds ONE optional\n * seam on top of that verbatim behavior: `setUrlStateRouter` lets a host whose\n * router must observe/perform the writes (react-router, a memory router in\n * tests, a native shell) inject `{ push, replace, getLocation? }`. With no\n * router injected — the default, and the Next.js wiring — behavior is\n * byte-identical to the original. The injected router lives on `globalThis`\n * under `Symbol.for(\"ai-matrx.kit.url-state-router\")` because the package\n * builds `splitting: false` dual ESM/CJS: module-level state would silently\n * split the registration across bundle graphs (the confirm-opener hazard).\n */\n\nimport {\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from \"react\";\n\nconst URL_STATE_EVENT = \"matrx:url-state\";\n\n/**\n * The optional injected router. `push`/`replace` receive the full relative\n * URL (`pathname?query#hash`) exactly as the History API default would write\n * it. `getLocation` overrides where the current URL is read from (a memory\n * router); absent, `window.location` is read.\n */\nexport interface UrlStateRouter {\n  push: (url: string) => void;\n  replace: (url: string) => void;\n  getLocation?: (() => { pathname: string; search: string; hash: string }) | undefined;\n}\n\nconst ROUTER_SLOT = Symbol.for(\"ai-matrx.kit.url-state-router\");\n\nfunction getRouter(): UrlStateRouter | null {\n  return (\n    (globalThis as Record<symbol, UrlStateRouter | null | undefined>)[\n      ROUTER_SLOT\n    ] ?? null\n  );\n}\n\n/**\n * Inject (or with `null` remove) the host router. Optional — with none set,\n * writes go through `window.history` push/replaceState, which is the verbatim\n * Matrx-frontend behavior and correct for Next.js App Router hosts.\n */\nexport function setUrlStateRouter(router: UrlStateRouter | null): void {\n  (globalThis as Record<symbol, UrlStateRouter | null | undefined>)[\n    ROUTER_SLOT\n  ] = router;\n}\n\nfunction currentLocation(): { pathname: string; search: string; hash: string } {\n  const custom = getRouter()?.getLocation;\n  if (custom) return custom();\n  return {\n    pathname: window.location.pathname,\n    search: window.location.search,\n    hash: window.location.hash,\n  };\n}\n\nfunction subscribeToUrl(listener: () => void) {\n  window.addEventListener(\"popstate\", listener);\n  window.addEventListener(URL_STATE_EVENT, listener);\n  return () => {\n    window.removeEventListener(\"popstate\", listener);\n    window.removeEventListener(URL_STATE_EVENT, listener);\n  };\n}\n\nfunction getUrlSnapshot() {\n  return currentLocation().search;\n}\n\nfunction getServerUrlSnapshot() {\n  return \"\";\n}\n\n/** Reactive query-string snapshot for URL-backed primitives. */\nexport function useUrlSearchParams(): URLSearchParams {\n  const search = useSyncExternalStore(\n    subscribeToUrl,\n    getUrlSnapshot,\n    getServerUrlSnapshot,\n  );\n  return useMemo(() => new URLSearchParams(search), [search]);\n}\n\nexport type UrlHistoryMode = \"push\" | \"replace\";\n\nexport interface UrlStateCodec<T> {\n  defaultValue: T;\n  parse: (raw: string | null) => T;\n  serialize: (value: T) => string | null;\n}\n\nexport interface SetUrlStateOptions {\n  history?: UrlHistoryMode | undefined;\n}\n\nexport function commitUrlParams(\n  patch: Readonly<Record<string, string | null>>,\n  history: UrlHistoryMode,\n) {\n  const location = currentLocation();\n  const params = new URLSearchParams(location.search);\n  for (const [key, value] of Object.entries(patch)) {\n    if (value === null || value === \"\") params.delete(key);\n    else params.set(key, value);\n  }\n\n  const query = params.toString();\n  const next = `${location.pathname}${query ? `?${query}` : \"\"}${location.hash}`;\n  const current = `${location.pathname}${location.search}${location.hash}`;\n  if (next === current) return;\n\n  const router = getRouter();\n  if (router) {\n    if (history === \"replace\") router.replace(next);\n    else router.push(next);\n  } else if (history === \"replace\") {\n    window.history.replaceState(window.history.state, \"\", next);\n  } else {\n    window.history.pushState(window.history.state, \"\", next);\n  }\n  window.dispatchEvent(new Event(URL_STATE_EVENT));\n}\n\n/**\n * Classify a URL transition for surfaces that MIRROR state (a store, local\n * state) into the URL from an effect, where there is no single call site to\n * label.\n *\n * THE RULE: a discrete user decision (tab, filter, sort, page, selection)\n * PUSHES, so Back undoes exactly that one step; only high-frequency text\n * (`textKeys` — search boxes, a slider being dragged) REPLACES, so one search\n * is one entry instead of one per keystroke.\n */\nexport function historyModeForParamChange(\n  current: URLSearchParams,\n  next: URLSearchParams,\n  textKeys: readonly string[],\n): UrlHistoryMode {\n  const keys = new Set([...current.keys(), ...next.keys()]);\n  const changed = [...keys].filter(\n    (key) => current.get(key) !== next.get(key),\n  );\n  if (changed.length === 0) return \"replace\";\n  return changed.every((key) => textKeys.includes(key)) ? \"replace\" : \"push\";\n}\n\nexport function useUrlState<T>(\n  key: string,\n  codec: UrlStateCodec<T>,\n): readonly [T, (value: T, options?: SetUrlStateOptions) => void] {\n  const searchParams = useUrlSearchParams();\n  const value = codec.parse(searchParams.get(key));\n\n  const setValue = (next: T, options?: SetUrlStateOptions) => {\n    commitUrlParams(\n      { [key]: codec.serialize(next) },\n      options?.history ?? \"push\",\n    );\n  };\n\n  return [value, setValue] as const;\n}\n\nexport function stringUrlCodec(defaultValue = \"\"): UrlStateCodec<string> {\n  return {\n    defaultValue,\n    parse: (raw) => raw ?? defaultValue,\n    serialize: (value) => (value === defaultValue ? null : value),\n  };\n}\n\nexport function enumUrlCodec<const T extends string>(\n  values: readonly T[],\n  defaultValue: T,\n): UrlStateCodec<T> {\n  const allowed = new Set<string>(values);\n  return {\n    defaultValue,\n    parse: (raw) => (raw && allowed.has(raw) ? (raw as T) : defaultValue),\n    serialize: (value) => (value === defaultValue ? null : value),\n  };\n}\n\nexport function booleanUrlCodec(defaultValue = false): UrlStateCodec<boolean> {\n  return {\n    defaultValue,\n    parse: (raw) => (raw === null ? defaultValue : raw === \"1\"),\n    serialize: (value) => (value === defaultValue ? null : value ? \"1\" : \"0\"),\n  };\n}\n\nexport function positiveIntegerUrlCodec(\n  defaultValue: number,\n): UrlStateCodec<number> {\n  return {\n    defaultValue,\n    parse: (raw) => {\n      const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;\n      return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultValue;\n    },\n    serialize: (value) =>\n      value === defaultValue || !Number.isFinite(value) || value <= 0\n        ? null\n        : String(Math.trunc(value)),\n  };\n}\n\nexport function jsonUrlCodec<T>(\n  defaultValue: T,\n  isValid: (value: unknown) => value is T,\n): UrlStateCodec<T> {\n  return {\n    defaultValue,\n    parse: (raw) => {\n      if (!raw) return defaultValue;\n      try {\n        const parsed: unknown = JSON.parse(raw);\n        return isValid(parsed) ? parsed : defaultValue;\n      } catch {\n        return defaultValue;\n      }\n    },\n    serialize: (value) =>\n      JSON.stringify(value) === JSON.stringify(defaultValue)\n        ? null\n        : JSON.stringify(value),\n  };\n}\n\n/**\n * Mirror a whole view-state OBJECT into the URL, in both directions.\n *\n * THE PATTERN 18 FILES WERE HAND-ROLLING. `useUrlState` is right when one\n * control owns one parameter. It is the wrong shape when a surface holds a\n * cluster of related values (search + sort + filters + page) that must move\n * together, be seeded from the URL on first render, and follow Back/Forward.\n * Every surface that needed that wrote its own `history.pushState` — and NONE\n * of them dispatched the sync event, so any other URL-backed control on the\n * same page silently kept showing stale values after they wrote.\n *\n * 🚨 THE LOOP IS BROKEN BY VALUE, NEVER BY BOOKKEEPING. The obvious guard —\n * remember the last URL you wrote and ignore anything matching it — looks\n * equivalent and is not: pressing Forward to a view already visited produces a\n * URL you did indeed write before, so the guard swallows it and the address bar\n * moves while the surface does not. Compare the DECODED value to the current\n * one instead; your own write compares equal and stops.\n *\n * Seeding happens in the `useState` initialiser, not an effect, so the first\n * render already shows the requested view rather than flashing the default and\n * fetching the wrong page before correcting itself.\n */\nexport interface MirroredUrlStateOptions<T> {\n  /** Decode the whole value from the query string. Must never throw. */\n  parse: (params: URLSearchParams) => T;\n  /** Encode it; `null` for a key means \"omit\", which keeps defaults out of the URL. */\n  toParams: (value: T) => Record<string, string | null>;\n  /** Value equality — what stops the two directions fighting. */\n  isSame: (a: T, b: T) => boolean;\n  /** Keys that REPLACE instead of pushing (search boxes, dragged sliders). */\n  textKeys?: readonly string[] | undefined;\n  /**\n   * Changing this clears the mirrored state and its parameters — for when the\n   * surface switches to a different subject and the old view would be a lie.\n   */\n  resetKey?: string | undefined;\n}\n\nexport function useMirroredUrlState<T>(\n  options: MirroredUrlStateOptions<T>,\n): readonly [T, (updater: T | ((prev: T) => T)) => void] {\n  const { parse, toParams, isSame, textKeys = [], resetKey } = options;\n  const params = useUrlSearchParams();\n\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n\n  const [value, setValue] = useState<T>(() =>\n    parse(\n      typeof window === \"undefined\"\n        ? new URLSearchParams()\n        : new URLSearchParams(currentLocation().search),\n    ),\n  );\n\n  // value → URL\n  useEffect(() => {\n    if (typeof window === \"undefined\") return;\n    const current = new URLSearchParams(currentLocation().search);\n    const patch = optionsRef.current.toParams(value);\n\n    const next = new URLSearchParams(current);\n    for (const [key, v] of Object.entries(patch)) {\n      if (v === null || v === \"\") next.delete(key);\n      else next.set(key, v);\n    }\n    if (next.toString() === current.toString()) return;\n\n    commitUrlParams(patch, historyModeForParamChange(current, next, textKeys));\n    // `textKeys` is a literal in every caller; `value` is the real trigger.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [value]);\n\n  // URL → value (Back/Forward, a pasted link, another control writing)\n  useEffect(() => {\n    // Read the URL at EFFECT time, not the render snapshot. The value→URL\n    // effect runs first. When it commits a local filter/sort decision it\n    // synchronously notifies the external store, but `params` in this render\n    // still describes the URL from before that write. Re-applying that stale\n    // snapshot here ping-pongs state and URL until React raises #185.\n    const fromUrl = optionsRef.current.parse(\n      new URLSearchParams(currentLocation().search),\n    );\n    setValue((prev) => (optionsRef.current.isSame(prev, fromUrl) ? prev : fromUrl));\n  }, [params]);\n\n  // Clearing on a subject change is deliberate; clearing on a subject ARRIVING\n  // is destructive. A surface whose id is undefined for its first render (async\n  // params, a late store hydration, a suspended boundary) would otherwise wipe\n  // the very view the user just loaded — and the symptom is indistinguishable\n  // from \"the URL never saved my filters\", because the write lands and is\n  // erased a tick later.\n  //\n  // So: only a transition between two REAL, DIFFERENT keys resets.\n  const previousResetKey = useRef(resetKey);\n  useEffect(() => {\n    const previous = previousResetKey.current;\n    previousResetKey.current = resetKey;\n    if (previous === resetKey) return;\n    if (previous === undefined || previous === \"\") return; // arriving, not changing\n    if (resetKey === undefined || resetKey === \"\") return; // leaving, not changing\n\n    const cleared = optionsRef.current.parse(new URLSearchParams());\n    setValue(cleared);\n    commitUrlParams(optionsRef.current.toParams(cleared), \"replace\");\n  }, [resetKey]);\n\n  const update = useCallback((updater: T | ((prev: T) => T)) => {\n    setValue((prev) =>\n      typeof updater === \"function\"\n        ? (updater as (p: T) => T)(prev)\n        : updater,\n    );\n  }, []);\n\n  return [value, update] as const;\n}\n"],"mappings":"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","names":[]}

package/dist/url-state.d.cts

@@ -0,0 +1,90 @@
+/**
+ * The optional injected router. `push`/`replace` receive the full relative
+ * URL (`pathname?query#hash`) exactly as the History API default would write
+ * it. `getLocation` overrides where the current URL is read from (a memory
+ * router); absent, `window.location` is read.
+ */
+interface UrlStateRouter {
+    push: (url: string) => void;
+    replace: (url: string) => void;
+    getLocation?: (() => {
+        pathname: string;
+        search: string;
+        hash: string;
+    }) | undefined;
+}
+/**
+ * Inject (or with `null` remove) the host router. Optional — with none set,
+ * writes go through `window.history` push/replaceState, which is the verbatim
+ * Matrx-frontend behavior and correct for Next.js App Router hosts.
+ */
+declare function setUrlStateRouter(router: UrlStateRouter | null): void;
+/** Reactive query-string snapshot for URL-backed primitives. */
+declare function useUrlSearchParams(): URLSearchParams;
+type UrlHistoryMode = "push" | "replace";
+interface UrlStateCodec<T> {
+    defaultValue: T;
+    parse: (raw: string | null) => T;
+    serialize: (value: T) => string | null;
+}
+interface SetUrlStateOptions {
+    history?: UrlHistoryMode | undefined;
+}
+declare function commitUrlParams(patch: Readonly<Record<string, string | null>>, history: UrlHistoryMode): void;
+/**
+ * Classify a URL transition for surfaces that MIRROR state (a store, local
+ * state) into the URL from an effect, where there is no single call site to
+ * label.
+ *
+ * THE RULE: a discrete user decision (tab, filter, sort, page, selection)
+ * PUSHES, so Back undoes exactly that one step; only high-frequency text
+ * (`textKeys` — search boxes, a slider being dragged) REPLACES, so one search
+ * is one entry instead of one per keystroke.
+ */
+declare function historyModeForParamChange(current: URLSearchParams, next: URLSearchParams, textKeys: readonly string[]): UrlHistoryMode;
+declare function useUrlState<T>(key: string, codec: UrlStateCodec<T>): readonly [T, (value: T, options?: SetUrlStateOptions) => void];
+declare function stringUrlCodec(defaultValue?: string): UrlStateCodec<string>;
+declare function enumUrlCodec<const T extends string>(values: readonly T[], defaultValue: T): UrlStateCodec<T>;
+declare function booleanUrlCodec(defaultValue?: boolean): UrlStateCodec<boolean>;
+declare function positiveIntegerUrlCodec(defaultValue: number): UrlStateCodec<number>;
+declare function jsonUrlCodec<T>(defaultValue: T, isValid: (value: unknown) => value is T): UrlStateCodec<T>;
+/**
+ * Mirror a whole view-state OBJECT into the URL, in both directions.
+ *
+ * THE PATTERN 18 FILES WERE HAND-ROLLING. `useUrlState` is right when one
+ * control owns one parameter. It is the wrong shape when a surface holds a
+ * cluster of related values (search + sort + filters + page) that must move
+ * together, be seeded from the URL on first render, and follow Back/Forward.
+ * Every surface that needed that wrote its own `history.pushState` — and NONE
+ * of them dispatched the sync event, so any other URL-backed control on the
+ * same page silently kept showing stale values after they wrote.
+ *
+ * 🚨 THE LOOP IS BROKEN BY VALUE, NEVER BY BOOKKEEPING. The obvious guard —
+ * remember the last URL you wrote and ignore anything matching it — looks
+ * equivalent and is not: pressing Forward to a view already visited produces a
+ * URL you did indeed write before, so the guard swallows it and the address bar
+ * moves while the surface does not. Compare the DECODED value to the current
+ * one instead; your own write compares equal and stops.
+ *
+ * Seeding happens in the `useState` initialiser, not an effect, so the first
+ * render already shows the requested view rather than flashing the default and
+ * fetching the wrong page before correcting itself.
+ */
+interface MirroredUrlStateOptions<T> {
+    /** Decode the whole value from the query string. Must never throw. */
+    parse: (params: URLSearchParams) => T;
+    /** Encode it; `null` for a key means "omit", which keeps defaults out of the URL. */
+    toParams: (value: T) => Record<string, string | null>;
+    /** Value equality — what stops the two directions fighting. */
+    isSame: (a: T, b: T) => boolean;
+    /** Keys that REPLACE instead of pushing (search boxes, dragged sliders). */
+    textKeys?: readonly string[] | undefined;
+    /**
+     * Changing this clears the mirrored state and its parameters — for when the
+     * surface switches to a different subject and the old view would be a lie.
+     */
+    resetKey?: string | undefined;
+}
+declare function useMirroredUrlState<T>(options: MirroredUrlStateOptions<T>): readonly [T, (updater: T | ((prev: T) => T)) => void];
+
+export { type MirroredUrlStateOptions, type SetUrlStateOptions, type UrlHistoryMode, type UrlStateCodec, type UrlStateRouter, booleanUrlCodec, commitUrlParams, enumUrlCodec, historyModeForParamChange, jsonUrlCodec, positiveIntegerUrlCodec, setUrlStateRouter, stringUrlCodec, useMirroredUrlState, useUrlSearchParams, useUrlState };

package/dist/url-state.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The optional injected router. `push`/`replace` receive the full relative
+ * URL (`pathname?query#hash`) exactly as the History API default would write
+ * it. `getLocation` overrides where the current URL is read from (a memory
+ * router); absent, `window.location` is read.
+ */
+interface UrlStateRouter {
+    push: (url: string) => void;
+    replace: (url: string) => void;
+    getLocation?: (() => {
+        pathname: string;
+        search: string;
+        hash: string;
+    }) | undefined;
+}
+/**
+ * Inject (or with `null` remove) the host router. Optional — with none set,
+ * writes go through `window.history` push/replaceState, which is the verbatim
+ * Matrx-frontend behavior and correct for Next.js App Router hosts.
+ */
+declare function setUrlStateRouter(router: UrlStateRouter | null): void;
+/** Reactive query-string snapshot for URL-backed primitives. */
+declare function useUrlSearchParams(): URLSearchParams;
+type UrlHistoryMode = "push" | "replace";
+interface UrlStateCodec<T> {
+    defaultValue: T;
+    parse: (raw: string | null) => T;
+    serialize: (value: T) => string | null;
+}
+interface SetUrlStateOptions {
+    history?: UrlHistoryMode | undefined;
+}
+declare function commitUrlParams(patch: Readonly<Record<string, string | null>>, history: UrlHistoryMode): void;
+/**
+ * Classify a URL transition for surfaces that MIRROR state (a store, local
+ * state) into the URL from an effect, where there is no single call site to
+ * label.
+ *
+ * THE RULE: a discrete user decision (tab, filter, sort, page, selection)
+ * PUSHES, so Back undoes exactly that one step; only high-frequency text
+ * (`textKeys` — search boxes, a slider being dragged) REPLACES, so one search
+ * is one entry instead of one per keystroke.
+ */
+declare function historyModeForParamChange(current: URLSearchParams, next: URLSearchParams, textKeys: readonly string[]): UrlHistoryMode;
+declare function useUrlState<T>(key: string, codec: UrlStateCodec<T>): readonly [T, (value: T, options?: SetUrlStateOptions) => void];
+declare function stringUrlCodec(defaultValue?: string): UrlStateCodec<string>;
+declare function enumUrlCodec<const T extends string>(values: readonly T[], defaultValue: T): UrlStateCodec<T>;
+declare function booleanUrlCodec(defaultValue?: boolean): UrlStateCodec<boolean>;
+declare function positiveIntegerUrlCodec(defaultValue: number): UrlStateCodec<number>;
+declare function jsonUrlCodec<T>(defaultValue: T, isValid: (value: unknown) => value is T): UrlStateCodec<T>;
+/**
+ * Mirror a whole view-state OBJECT into the URL, in both directions.
+ *
+ * THE PATTERN 18 FILES WERE HAND-ROLLING. `useUrlState` is right when one
+ * control owns one parameter. It is the wrong shape when a surface holds a
+ * cluster of related values (search + sort + filters + page) that must move
+ * together, be seeded from the URL on first render, and follow Back/Forward.
+ * Every surface that needed that wrote its own `history.pushState` — and NONE
+ * of them dispatched the sync event, so any other URL-backed control on the
+ * same page silently kept showing stale values after they wrote.
+ *
+ * 🚨 THE LOOP IS BROKEN BY VALUE, NEVER BY BOOKKEEPING. The obvious guard —
+ * remember the last URL you wrote and ignore anything matching it — looks
+ * equivalent and is not: pressing Forward to a view already visited produces a
+ * URL you did indeed write before, so the guard swallows it and the address bar
+ * moves while the surface does not. Compare the DECODED value to the current
+ * one instead; your own write compares equal and stops.
+ *
+ * Seeding happens in the `useState` initialiser, not an effect, so the first
+ * render already shows the requested view rather than flashing the default and
+ * fetching the wrong page before correcting itself.
+ */
+interface MirroredUrlStateOptions<T> {
+    /** Decode the whole value from the query string. Must never throw. */
+    parse: (params: URLSearchParams) => T;
+    /** Encode it; `null` for a key means "omit", which keeps defaults out of the URL. */
+    toParams: (value: T) => Record<string, string | null>;
+    /** Value equality — what stops the two directions fighting. */
+    isSame: (a: T, b: T) => boolean;
+    /** Keys that REPLACE instead of pushing (search boxes, dragged sliders). */
+    textKeys?: readonly string[] | undefined;
+    /**
+     * Changing this clears the mirrored state and its parameters — for when the
+     * surface switches to a different subject and the old view would be a lie.
+     */
+    resetKey?: string | undefined;
+}
+declare function useMirroredUrlState<T>(options: MirroredUrlStateOptions<T>): readonly [T, (updater: T | ((prev: T) => T)) => void];
+
+export { type MirroredUrlStateOptions, type SetUrlStateOptions, type UrlHistoryMode, type UrlStateCodec, type UrlStateRouter, booleanUrlCodec, commitUrlParams, enumUrlCodec, historyModeForParamChange, jsonUrlCodec, positiveIntegerUrlCodec, setUrlStateRouter, stringUrlCodec, useMirroredUrlState, useUrlSearchParams, useUrlState };

package/dist/url-state.js

@@ -0,0 +1,199 @@
+"use client";
+"use client";
+
+// src/url-state.ts
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore
+} from "react";
+var URL_STATE_EVENT = "matrx:url-state";
+var ROUTER_SLOT = /* @__PURE__ */ Symbol.for("ai-matrx.kit.url-state-router");
+function getRouter() {
+  return globalThis[ROUTER_SLOT] ?? null;
+}
+function setUrlStateRouter(router) {
+  globalThis[ROUTER_SLOT] = router;
+}
+function currentLocation() {
+  const custom = getRouter()?.getLocation;
+  if (custom) return custom();
+  return {
+    pathname: window.location.pathname,
+    search: window.location.search,
+    hash: window.location.hash
+  };
+}
+function subscribeToUrl(listener) {
+  window.addEventListener("popstate", listener);
+  window.addEventListener(URL_STATE_EVENT, listener);
+  return () => {
+    window.removeEventListener("popstate", listener);
+    window.removeEventListener(URL_STATE_EVENT, listener);
+  };
+}
+function getUrlSnapshot() {
+  return currentLocation().search;
+}
+function getServerUrlSnapshot() {
+  return "";
+}
+function useUrlSearchParams() {
+  const search = useSyncExternalStore(
+    subscribeToUrl,
+    getUrlSnapshot,
+    getServerUrlSnapshot
+  );
+  return useMemo(() => new URLSearchParams(search), [search]);
+}
+function commitUrlParams(patch, history) {
+  const location = currentLocation();
+  const params = new URLSearchParams(location.search);
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null || value === "") params.delete(key);
+    else params.set(key, value);
+  }
+  const query = params.toString();
+  const next = `${location.pathname}${query ? `?${query}` : ""}${location.hash}`;
+  const current = `${location.pathname}${location.search}${location.hash}`;
+  if (next === current) return;
+  const router = getRouter();
+  if (router) {
+    if (history === "replace") router.replace(next);
+    else router.push(next);
+  } else if (history === "replace") {
+    window.history.replaceState(window.history.state, "", next);
+  } else {
+    window.history.pushState(window.history.state, "", next);
+  }
+  window.dispatchEvent(new Event(URL_STATE_EVENT));
+}
+function historyModeForParamChange(current, next, textKeys) {
+  const keys = /* @__PURE__ */ new Set([...current.keys(), ...next.keys()]);
+  const changed = [...keys].filter(
+    (key) => current.get(key) !== next.get(key)
+  );
+  if (changed.length === 0) return "replace";
+  return changed.every((key) => textKeys.includes(key)) ? "replace" : "push";
+}
+function useUrlState(key, codec) {
+  const searchParams = useUrlSearchParams();
+  const value = codec.parse(searchParams.get(key));
+  const setValue = (next, options) => {
+    commitUrlParams(
+      { [key]: codec.serialize(next) },
+      options?.history ?? "push"
+    );
+  };
+  return [value, setValue];
+}
+function stringUrlCodec(defaultValue = "") {
+  return {
+    defaultValue,
+    parse: (raw) => raw ?? defaultValue,
+    serialize: (value) => value === defaultValue ? null : value
+  };
+}
+function enumUrlCodec(values, defaultValue) {
+  const allowed = new Set(values);
+  return {
+    defaultValue,
+    parse: (raw) => raw && allowed.has(raw) ? raw : defaultValue,
+    serialize: (value) => value === defaultValue ? null : value
+  };
+}
+function booleanUrlCodec(defaultValue = false) {
+  return {
+    defaultValue,
+    parse: (raw) => raw === null ? defaultValue : raw === "1",
+    serialize: (value) => value === defaultValue ? null : value ? "1" : "0"
+  };
+}
+function positiveIntegerUrlCodec(defaultValue) {
+  return {
+    defaultValue,
+    parse: (raw) => {
+      const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;
+      return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultValue;
+    },
+    serialize: (value) => value === defaultValue || !Number.isFinite(value) || value <= 0 ? null : String(Math.trunc(value))
+  };
+}
+function jsonUrlCodec(defaultValue, isValid) {
+  return {
+    defaultValue,
+    parse: (raw) => {
+      if (!raw) return defaultValue;
+      try {
+        const parsed = JSON.parse(raw);
+        return isValid(parsed) ? parsed : defaultValue;
+      } catch {
+        return defaultValue;
+      }
+    },
+    serialize: (value) => JSON.stringify(value) === JSON.stringify(defaultValue) ? null : JSON.stringify(value)
+  };
+}
+function useMirroredUrlState(options) {
+  const { parse, toParams, isSame, textKeys = [], resetKey } = options;
+  const params = useUrlSearchParams();
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const [value, setValue] = useState(
+    () => parse(
+      typeof window === "undefined" ? new URLSearchParams() : new URLSearchParams(currentLocation().search)
+    )
+  );
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const current = new URLSearchParams(currentLocation().search);
+    const patch = optionsRef.current.toParams(value);
+    const next = new URLSearchParams(current);
+    for (const [key, v] of Object.entries(patch)) {
+      if (v === null || v === "") next.delete(key);
+      else next.set(key, v);
+    }
+    if (next.toString() === current.toString()) return;
+    commitUrlParams(patch, historyModeForParamChange(current, next, textKeys));
+  }, [value]);
+  useEffect(() => {
+    const fromUrl = optionsRef.current.parse(
+      new URLSearchParams(currentLocation().search)
+    );
+    setValue((prev) => optionsRef.current.isSame(prev, fromUrl) ? prev : fromUrl);
+  }, [params]);
+  const previousResetKey = useRef(resetKey);
+  useEffect(() => {
+    const previous = previousResetKey.current;
+    previousResetKey.current = resetKey;
+    if (previous === resetKey) return;
+    if (previous === void 0 || previous === "") return;
+    if (resetKey === void 0 || resetKey === "") return;
+    const cleared = optionsRef.current.parse(new URLSearchParams());
+    setValue(cleared);
+    commitUrlParams(optionsRef.current.toParams(cleared), "replace");
+  }, [resetKey]);
+  const update = useCallback((updater) => {
+    setValue(
+      (prev) => typeof updater === "function" ? updater(prev) : updater
+    );
+  }, []);
+  return [value, update];
+}
+export {
+  booleanUrlCodec,
+  commitUrlParams,
+  enumUrlCodec,
+  historyModeForParamChange,
+  jsonUrlCodec,
+  positiveIntegerUrlCodec,
+  setUrlStateRouter,
+  stringUrlCodec,
+  useMirroredUrlState,
+  useUrlSearchParams,
+  useUrlState
+};
+//# sourceMappingURL=url-state.js.map