@mindees/router 0.1.0

package/dist/router.d.ts

@@ -0,0 +1,217 @@
+import { RouterHistory, RouterLocation, createHref } from "./history.js";
+import { LoaderData, LoaderDepsFn, LoaderFn } from "./data.js";
+import { HasPathParams, PathParams } from "./pattern.js";
+import { StandardSchemaV1 } from "./standard-schema.js";
+import { QueryValue } from "./search.js";
+import { Component, MindeesNode } from "@mindees/core";
+
+//#region src/router.d.ts
+/**
+ * Props a route's component receives from {@link createRouterView}. `params` and
+ * `search` are **reactive accessors** (read them in a reactive scope so a
+ * same-route param change updates in place, no re-mount); `children` is the
+ * matched **child route** — render it wherever the nested route should appear
+ * (the "outlet"). See ADR-0004.
+ */
+interface RouteComponentProps {
+  /** The router instance (for `navigate`/`select`). */
+  router: Router;
+  /** Reactive accessor for the current (merged) path params. */
+  params: () => Record<string, string>;
+  /** Reactive accessor for the current search params. */
+  search: () => Record<string, unknown>;
+  /** Reactive accessor for this route's loader state (`idle` when it has no loader). */
+  data: () => LoaderData;
+  /** The matched child route (the outlet); render it to show nested routes. */
+  children: MindeesNode;
+}
+/** A route: a path pattern, an optional component, optional search schema, and optional children. */
+interface RouteRecord {
+  /**
+   * The path pattern. At the top level this is absolute (`/posts/:postId`); a
+   * nested route's path is **relative to its parent** (`settings`), and a child
+   * with `''` or `'/'` is the parent's **index** route.
+   */
+  path: string;
+  /** The component to render for this route. A component-less route passes its child through. */
+  component?: Component<RouteComponentProps>;
+  /**
+   * A Standard Schema validating this route's search params. Its **output must
+   * be object-shaped** (search params are a record), so a non-object schema like
+   * `z.string()` is rejected at compile time and validated results need no cast.
+   *
+   * Note: only the **matched leaf** route's `searchSchema` is applied — a schema
+   * on a parent/layout route is currently not used (search is global to the URL;
+   * the leaf governs it). Per-route end-to-end `InferOutput` typing through
+   * `Router.search()` arrives with the typed route registry (a later phase).
+   */
+  searchSchema?: StandardSchemaV1<unknown, Record<string, unknown>>;
+  /** Data loader for this route (sync or async); result is exposed via `data()`. */
+  loader?: LoaderFn;
+  /** Declares which inputs key this route's loader cache (e.g. specific search params). */
+  loaderDeps?: LoaderDepsFn;
+  /** Stale-while-revalidate window in ms; within it a successful load is reused. */
+  staleTime?: number;
+  /** Nested child routes (their `path` is relative to this route). */
+  children?: readonly RouteRecord[];
+  /** Arbitrary route metadata. */
+  meta?: Readonly<Record<string, unknown>>;
+}
+/** The result of matching a location against the route table. */
+interface RouteMatch {
+  /** The matched route record. */
+  route: RouteRecord;
+  /** The matched pathname. */
+  pathname: string;
+  /** Path params extracted from the pattern. */
+  params: Record<string, string>;
+  /** Search params — validated output when a schema is present, else the raw parse. */
+  search: Record<string, unknown>;
+  /** The raw parsed query, before schema validation. */
+  searchRaw: Record<string, string | string[]>;
+  /** Search-validation issues, present only when validation failed. */
+  issues?: ReadonlyArray<StandardSchemaV1.Issue>;
+}
+/** The router's reactive state — a snapshot read through fine-grained signals. */
+interface RouterState {
+  /** The current location. */
+  location: RouterLocation;
+  /**
+   * The matched route **chain**, root → leaf (one entry per nesting level), or
+   * empty when nothing matched. Drives nested rendering ({@link createRouterView}).
+   */
+  matches: readonly RouteMatch[];
+  /** The matched **leaf** route, or `null` if nothing matched. */
+  match: RouteMatch | null;
+  /** Convenience: the current pathname. */
+  pathname: string;
+  /** Convenience: the current path params (`{}` when unmatched). */
+  params: Record<string, string>;
+  /** Convenience: the current search params (`{}` when unmatched). */
+  search: Record<string, unknown>;
+}
+/** Options that apply to any navigation. */
+interface NavigateOptions {
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean;
+  /** Navigate even if the target equals the current location (skips the idempotent no-op). */
+  force?: boolean;
+  /**
+   * Wrap the update in `document.startViewTransition` when available (web only).
+   * Overrides the router-level `viewTransitions` default. No-op outside a DOM.
+   */
+  viewTransition?: boolean;
+}
+/**
+ * A navigation guard. Run before each navigation with the target and current
+ * hrefs. Return `false` to cancel, a string to redirect, or nothing to proceed.
+ */
+type BeforeNavigate = (to: string, from: string) => boolean | string | undefined;
+/** The params/search/hash carried by a structured target, with params required iff the pattern has them. */
+type NavExtras<P extends string> = {
+  /** Search params to serialize into the query string. */search?: Record<string, QueryValue>; /** A hash fragment (with or without a leading `#`). */
+  hash?: string;
+} & (HasPathParams<P> extends true ? {
+  params: PathParams<P>;
+} : {
+  params?: Record<string, never>;
+});
+/**
+ * A fully-typed structured navigation target. `to` is a path pattern; `params`
+ * is **required** when the pattern has dynamic segments and forbidden otherwise
+ * — inferred from `to` with zero codegen.
+ *
+ * The param requirement is enforced when `to` is a **string literal**. If `to`
+ * is a widened `string` (e.g. read from a variable typed `string`), its segments
+ * can't be inferred, so `params` is not type-checked — a missing required param
+ * then throws {@link RouterError} (`MISSING_PARAM`) at runtime.
+ *
+ * @example
+ * router.navigate({ to: '/posts/:postId', params: { postId: '42' } })
+ * router.navigate({ to: '/about' }) // no params allowed
+ */
+type NavTarget<P extends string> = {
+  to: P;
+} & NavExtras<P>;
+/** Options for {@link createRouter}. */
+interface CreateRouterOptions {
+  /** The route table. Order is irrelevant — routes are matched most-specific first. */
+  routes: readonly RouteRecord[];
+  /** The history adapter. Defaults to an in-memory history at `/`. */
+  history?: RouterHistory;
+  /** A guard run before each navigation (cancel with `false`, redirect with a string). */
+  beforeNavigate?: BeforeNavigate;
+  /** Wrap navigations in `document.startViewTransition` by default (web only). */
+  viewTransitions?: boolean;
+}
+/** A live router instance. */
+interface Router {
+  /** The full reactive state snapshot. */
+  state(): RouterState;
+  /** The current location. */
+  location(): RouterLocation;
+  /** The matched route chain (root → leaf), or empty when unmatched. */
+  matches(): readonly RouteMatch[];
+  /** The current leaf match, or `null`. */
+  match(): RouteMatch | null;
+  /** The current path params (`{}` when unmatched). */
+  params(): Record<string, string>;
+  /** The current search params (`{}` when unmatched). */
+  search(): Record<string, unknown>;
+  /**
+   * Subscribe to a derived slice of router state with re-render isolation. The
+   * returned accessor (a memo) only changes when `selector(state)` changes under
+   * `equals` (default `Object.is`) — the same selector-isolation technique as
+   * core's Phase 2 `createProvider` (a computed memo over an `equals:false`
+   * source), applied to route state.
+   */
+  select<S>(selector: (state: RouterState) => S, equals?: (a: S, b: S) => boolean): () => S;
+  /** Navigate to a typed target or a (possibly relative) href string. */
+  navigate<P extends string>(target: string | NavTarget<P>, options?: NavigateOptions): void;
+  /** Reactively read a match's loader state (`idle` when the route has no loader). */
+  loaderData(match: RouteMatch): LoaderData;
+  /** Re-run the current chain's loaders (marks their cached data stale first). */
+  invalidate(): void;
+  /**
+   * Run a target href's loaders WITHOUT navigating (intent prefetch). A
+   * still-in-flight preload is aborted if you then navigate to a *different*
+   * route; once it settles it warms the cache for that route's next visit
+   * (subject to `staleTime`).
+   */
+  preload(to: string): void;
+  /**
+   * Replace the route table and re-match the current location **in place** — the
+   * location is preserved (dynamic reconfiguration without state reset).
+   */
+  setRoutes(routes: readonly RouteRecord[]): void;
+  /**
+   * The active route table, as provided to {@link createRouter} / {@link Router.setRoutes}
+   * (the nested tree, in insertion order). Matching internally flattens the tree
+   * and orders leaves by specificity (static > dynamic > catch-all); that
+   * precedence is an implementation detail, not the shape returned here.
+   */
+  routes(): readonly RouteRecord[];
+  /** The underlying history adapter. */
+  readonly history: RouterHistory;
+  /** Tear down the router's reactive scope and history subscription. */
+  dispose(): void;
+}
+/**
+ * Resolve a (possibly relative) path against a base pathname. Absolute paths
+ * (leading `/`) ignore the base; `.`/`..` segments are applied against it,
+ * treating the base pathname as a directory.
+ *
+ * @example
+ * resolvePath('/a/b', '/x')      // '/a/b'
+ * resolvePath('edit', '/posts/1') // '/posts/1/edit'
+ * resolvePath('../', '/posts/1')  // '/posts'
+ */
+declare function resolvePath(to: string, from: string): string;
+/**
+ * Create a router over a route table. State is reactive (signals); call
+ * {@link Router.dispose} to tear it down.
+ */
+declare function createRouter(options: CreateRouterOptions): Router;
+//#endregion
+export { BeforeNavigate, CreateRouterOptions, NavTarget, NavigateOptions, RouteComponentProps, RouteMatch, RouteRecord, Router, RouterState, createRouter, resolvePath };
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","names":[],"sources":["../src/router.ts"],"mappings":";;;;;;;;;;;;;;;UA0DiB,mBAAA;EAUf;EARA,MAAA,EAAQ,MAAA;EAQa;EANrB,MAAA,QAAc,MAAA;EAUC;EARf,MAAA,QAAc,MAAA;;EAEd,IAAA,QAAY,UAAA;EAcA;EAZZ,QAAA,EAAU,WAAA;AAAA;;UAIK,WAAA;EA2BK;;;;;EArBpB,IAAA;EAEA;EAAA,SAAA,GAAY,SAAA,CAAU,mBAAA;EAAA;;;;;;;;;;EAWtB,YAAA,GAAe,gBAAA,UAA0B,MAAA;EAUzC;EARA,MAAA,GAAS,QAAA;EAQO;EANhB,UAAA,GAAa,YAAA;EAMS;EAJtB,SAAA;EAQyB;EANzB,QAAA,YAAoB,WAAA;EAQb;EANP,IAAA,GAAO,QAAA,CAAS,MAAA;AAAA;;UAID,UAAA;EAYN;EAVT,KAAA,EAAO,WAAA;EAUe;EARtB,QAAA;EAFO;EAIP,MAAA,EAAQ,MAAA;EAAR;EAEA,MAAA,EAAQ,MAAA;EAAR;EAEA,SAAA,EAAW,MAAA;EAAX;EAEA,MAAA,GAAS,aAAA,CAAc,gBAAA,CAAiB,KAAA;AAAA;;UAIzB,WAAA;EAJyB;EAMxC,QAAA,EAAU,cAAA;EANmC;AAI/C;;;EAOE,OAAA,WAAkB,UAAA;EAAA;EAElB,KAAA,EAAO,UAAA;EAIC;EAFR,QAAA;EAIc;EAFd,MAAA,EAAQ,MAAA;EAXR;EAaA,MAAA,EAAQ,MAAA;AAAA;;UAQO,eAAA;EAdR;EAgBP,OAAA;EAZA;EAcA,KAAA;EAZA;;;AAAc;EAiBd,cAAA;AAAA;;;;;KAOU,cAAA,IAAkB,EAAA,UAAY,IAAY;;KAGjD,SAAA;EAHO,wDAKV,MAAA,GAAS,MAAA,SAAe,UAAA;EAExB,IAAA;AAAA,KACG,aAAA,CAAc,CAAA;EAAoB,MAAA,EAAQ,UAAA,CAAW,CAAA;AAAA;EAAS,MAAA,GAAS,MAAA;AAAA;;;;;;;;;;;;;;;KAgBhE,SAAA;EAAgC,EAAA,EAAI,CAAA;AAAA,IAAM,SAAA,CAAU,CAAA;;UAe/C,mBAAA;EA/B2D;EAiC1E,MAAA,WAAiB,WAAA;EAjC+D;EAmChF,OAAA,GAAU,aAAA;EAnBS;EAqBnB,cAAA,GAAiB,cAAA;EArB6B;EAuB9C,eAAA;AAAA;;UAIe,MAAA;EA3BK;EA6BpB,KAAA,IAAS,WAAA;EA7BqC;EA+B9C,QAAA,IAAY,cAAA;EA/BkD;EAiC9D,OAAA,aAAoB,UAAA;EAjC2C;EAmC/D,KAAA,IAAS,UAAA;EApByB;EAsBlC,MAAA,IAAU,MAAA;EApBO;EAsBjB,MAAA,IAAU,MAAA;EAlBO;;;;;;;EA0BjB,MAAA,IAAU,QAAA,GAAW,KAAA,EAAO,WAAA,KAAgB,CAAA,EAAG,MAAA,IAAU,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAA,qBAAsB,CAAA;EA1BvE;EA4BjB,QAAA,mBAA2B,MAAA,WAAiB,SAAA,CAAU,CAAA,GAAI,OAAA,GAAU,eAAA;EA1BrD;EA4Bf,UAAA,CAAW,KAAA,EAAO,UAAA,GAAa,UAAA;EAxBhB;EA0Bf,UAAA;EA1BqB;;;;;;EAiCrB,OAAA,CAAQ,EAAA;EAboB;;;;EAkB5B,SAAA,CAAU,MAAA,WAAiB,WAAA;EAhB2B;;;;;;EAuBtD,MAAA,aAAmB,WAAA;EAED;EAAA,SAAT,OAAA,EAAS,aAAA;EAAa;EAE/B,OAAA;AAAA;;;;;;;;;;;iBAwGc,WAAA,CAAY,EAAA,UAAY,IAAY;;;;;iBA+CpC,YAAA,CAAa,OAAA,EAAS,mBAAA,GAAsB,MAAM"}

package/dist/router.js

@@ -0,0 +1,263 @@
+import { buildPath, compareSpecificity, matchPattern } from "./pattern.js";
+import { parseQuery, safeValidateSearch, stringifyQuery } from "./search.js";
+import { createHref, createMemoryHistory, parseHref } from "./history.js";
+import { createLoaderManager } from "./data.js";
+import { computed, createRoot, effect, signal } from "@mindees/core";
+//#region src/router.ts
+/**
+* The Quantum router — signals-native routing state with typed, validated
+* navigation and re-render isolation.
+*
+* Router state (location, params, search, matched route) is modeled as the
+* fine-grained signal graph from `@mindees/core` (Phase 1 `signal`/`computed`,
+* Phase 2 selector isolation). Consumers read a slice via {@link Router.select}
+* and re-run **only** when that slice changes — no whole-tree re-render on
+* navigation, no global-vs-local hook trap (cf. Expo Router). See ADR-0003.
+*
+* @module
+*/
+const EMPTY_PARAMS = Object.freeze({});
+const EMPTY_SEARCH = Object.freeze({});
+const EMPTY_MATCHES = Object.freeze([]);
+/** Join a parent path and a (relative) child path into a normalized full path. */
+function joinPaths(parent, child) {
+	const base = parent.endsWith("/") ? parent.slice(0, -1) : parent;
+	const rel = child.startsWith("/") ? child.slice(1) : child;
+	if (rel.length === 0) return base.length === 0 ? "/" : base;
+	return `${base}/${rel}`;
+}
+/**
+* Flatten a (possibly nested) route tree into leaf entries, each carrying its
+* full path and the root→leaf chain of records. A route with children
+* contributes only via its children (add an index child — `path: ''` — to match
+* the parent's own path).
+*/
+function flattenRouteTree(routes, parentPath, parentChain) {
+	const out = [];
+	for (const route of routes) {
+		const fullPath = joinPaths(parentPath, route.path);
+		const chain = [...parentChain, route];
+		if (route.children && route.children.length > 0) out.push(...flattenRouteTree(route.children, fullPath, chain));
+		else out.push({
+			fullPath,
+			chain
+		});
+	}
+	return out;
+}
+/** Flatten + sort a route tree most-specific first (static > dynamic > catch-all). */
+function compileRoutes(routes) {
+	return flattenRouteTree(routes, "", []).sort((a, b) => compareSpecificity(a.fullPath, b.fullPath));
+}
+/**
+* Match a location against the compiled route table, returning the matched chain
+* (root → leaf), or an empty array if nothing matched. Search is validated
+* against the **leaf** route's schema and shared across the chain.
+*/
+function matchLocation(flat, location) {
+	for (const fr of flat) {
+		const params = matchPattern(fr.fullPath, location.pathname);
+		if (params === null) continue;
+		const searchRaw = parseQuery(location.search);
+		let search = searchRaw;
+		let issues;
+		const leaf = fr.chain[fr.chain.length - 1];
+		if (leaf?.searchSchema) try {
+			const result = safeValidateSearch(leaf.searchSchema, searchRaw);
+			if (result.ok) search = result.value;
+			else issues = result.issues;
+		} catch (err) {
+			issues = [{ message: err instanceof Error ? err.message : "search validation failed" }];
+		}
+		return fr.chain.map((route) => {
+			const base = {
+				route,
+				pathname: location.pathname,
+				params,
+				search,
+				searchRaw
+			};
+			return issues ? {
+				...base,
+				issues
+			} : base;
+		});
+	}
+	return EMPTY_MATCHES;
+}
+/**
+* Resolve a (possibly relative) path against a base pathname. Absolute paths
+* (leading `/`) ignore the base; `.`/`..` segments are applied against it,
+* treating the base pathname as a directory.
+*
+* @example
+* resolvePath('/a/b', '/x')      // '/a/b'
+* resolvePath('edit', '/posts/1') // '/posts/1/edit'
+* resolvePath('../', '/posts/1')  // '/posts'
+*/
+function resolvePath(to, from) {
+	const stack = to.startsWith("/") ? [] : from.split("/").filter((s) => s.length > 0);
+	for (const seg of to.split("/")) {
+		if (seg === "" || seg === ".") continue;
+		if (seg === "..") stack.pop();
+		else stack.push(seg);
+	}
+	return `/${stack.join("/")}`;
+}
+/** Resolve an href string (which may be relative and carry query/hash) against a location. */
+function resolveHref(to, from) {
+	const hasPath = to.length > 0 && to[0] !== "?" && to[0] !== "#";
+	let rest = to;
+	let hash = "";
+	const hashIndex = rest.indexOf("#");
+	if (hashIndex !== -1) {
+		hash = rest.slice(hashIndex);
+		rest = rest.slice(0, hashIndex);
+	}
+	let search = "";
+	const queryIndex = rest.indexOf("?");
+	if (queryIndex !== -1) {
+		search = rest.slice(queryIndex);
+		rest = rest.slice(0, queryIndex);
+	}
+	return `${hasPath ? resolvePath(rest, from.pathname) : from.pathname}${!hasPath && queryIndex === -1 ? from.search : search}${hash}`;
+}
+/** Build an href from a structured navigation target. */
+function buildHref(target) {
+	const pathname = buildPath(target.to, target.params ?? {});
+	const query = target.search ? stringifyQuery(target.search) : "";
+	let hash = target.hash ?? "";
+	if (hash.length > 0 && !hash.startsWith("#")) hash = `#${hash}`;
+	return `${pathname}${query ? `?${query}` : ""}${hash}`;
+}
+/**
+* Create a router over a route table. State is reactive (signals); call
+* {@link Router.dispose} to tear it down.
+*/
+function createRouter(options) {
+	const history = options.history ?? createMemoryHistory();
+	let routesSig;
+	let flatMemo;
+	let locationSig;
+	let stateMemo;
+	let loaders;
+	const dispose = createRoot((disposeRoot) => {
+		routesSig = signal(options.routes, { equals: false });
+		flatMemo = computed(() => compileRoutes(routesSig()));
+		locationSig = signal(history.location(), { equals: false });
+		const matchMemo = computed(() => matchLocation(flatMemo(), locationSig()));
+		stateMemo = computed(() => {
+			const location = locationSig();
+			const matches = matchMemo();
+			const leaf = matches.length > 0 ? matches[matches.length - 1] ?? null : null;
+			return {
+				location,
+				matches,
+				match: leaf,
+				pathname: location.pathname,
+				params: leaf ? leaf.params : EMPTY_PARAMS,
+				search: leaf ? leaf.search : EMPTY_SEARCH
+			};
+		});
+		const dataVersion = signal(0, { equals: false });
+		loaders = createLoaderManager({
+			location: () => locationSig(),
+			onChange: () => dataVersion.set(0),
+			track: () => {
+				dataVersion();
+			}
+		});
+		effect(() => loaders.sync(matchMemo()));
+		const unsubscribe = history.subscribe((loc) => locationSig.set(loc));
+		return () => {
+			unsubscribe();
+			loaders.dispose();
+			disposeRoot();
+		};
+	});
+	/** Apply the navigation guard, following redirects (capped). Returns the final href, or null to cancel. */
+	const applyGuard = (href) => {
+		const guard = options.beforeNavigate;
+		if (!guard) return href;
+		let current = href;
+		for (let i = 0; i < 10; i++) {
+			const result = guard(current, createHref(locationSig()));
+			if (result === false) return null;
+			if (typeof result === "string") {
+				const next = resolveHref(result, locationSig());
+				if (next === current) return current;
+				current = next;
+				continue;
+			}
+			return current;
+		}
+		return null;
+	};
+	const navigate = (target, opts) => {
+		const href = applyGuard(typeof target === "string" ? resolveHref(target, locationSig()) : buildHref(target));
+		if (href === null) return;
+		if (opts?.force !== true && href === createHref(locationSig())) return;
+		const commit = () => {
+			if (opts?.replace) history.replace(href);
+			else history.push(href);
+		};
+		if (opts?.viewTransition ?? options.viewTransitions ?? false) startViewTransition(commit);
+		else commit();
+	};
+	const preload = (to) => {
+		const href = resolveHref(to, locationSig());
+		loaders.preload(matchLocation(flatMemo(), parseHref(href)));
+	};
+	return {
+		state: () => stateMemo(),
+		location: () => locationSig(),
+		matches: () => stateMemo().matches,
+		match: () => stateMemo().match,
+		params: () => stateMemo().params,
+		search: () => stateMemo().search,
+		select: (selector, equals = Object.is) => computed(() => selector(stateMemo()), { equals }),
+		navigate,
+		loaderData: (match) => loaders.read(match),
+		invalidate: () => loaders.invalidate(stateMemo().matches),
+		preload,
+		setRoutes: (routes) => routesSig.set(routes),
+		routes: () => routesSig(),
+		history,
+		dispose
+	};
+}
+/**
+* Run `commit` inside `document.startViewTransition` when available (web only),
+* else run it directly. The signals re-render is synchronous, so it happens
+* inside the transition. No-op-wrapping outside a DOM (SSR, native, tests).
+*
+* View transitions are a progressive enhancement, so this must NEVER throw out of
+* navigate() or leak an unhandled rejection: (1) a rapid second navigation aborts
+* the first transition and rejects its eagerly-created `ready`/`updateCallbackDone`
+* promises — we mark those handled; (2) some browsers throw synchronously (e.g. a
+* hidden/background document) — we fall back to a plain commit so the navigation
+* still lands (without committing twice).
+*/
+function startViewTransition(commit) {
+	const doc = typeof document === "undefined" ? void 0 : document;
+	if (!doc?.startViewTransition) {
+		commit();
+		return;
+	}
+	let committed = false;
+	const runCommit = () => {
+		committed = true;
+		commit();
+	};
+	try {
+		const transition = doc.startViewTransition(runCommit);
+		transition?.ready?.catch(() => {});
+		transition?.updateCallbackDone?.catch(() => {});
+	} catch {
+		if (!committed) commit();
+	}
+}
+//#endregion
+export { createRouter, resolvePath };
+
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","names":[],"sources":["../src/router.ts"],"sourcesContent":["/**\n * The Quantum router — signals-native routing state with typed, validated\n * navigation and re-render isolation.\n *\n * Router state (location, params, search, matched route) is modeled as the\n * fine-grained signal graph from `@mindees/core` (Phase 1 `signal`/`computed`,\n * Phase 2 selector isolation). Consumers read a slice via {@link Router.select}\n * and re-run **only** when that slice changes — no whole-tree re-render on\n * navigation, no global-vs-local hook trap (cf. Expo Router). See ADR-0003.\n *\n * @module\n */\n\nimport {\n  type Component,\n  computed,\n  createRoot,\n  effect,\n  type Memo,\n  type MindeesNode,\n  type Signal,\n  signal,\n} from '@mindees/core'\nimport {\n  createLoaderManager,\n  type LoaderData,\n  type LoaderDepsFn,\n  type LoaderFn,\n  type LoaderManager,\n} from './data'\nimport {\n  createHref,\n  createMemoryHistory,\n  parseHref,\n  type RouterHistory,\n  type RouterLocation,\n} from './history'\nimport {\n  buildPath,\n  compareSpecificity,\n  type HasPathParams,\n  matchPattern,\n  type PathParams,\n} from './pattern'\nimport { parseQuery, type QueryValue, safeValidateSearch, stringifyQuery } from './search'\nimport type { StandardSchemaV1 } from './standard-schema'\n\n// ---------------------------------------------------------------------------\n// Route table types\n// ---------------------------------------------------------------------------\n\n/**\n * Props a route's component receives from {@link createRouterView}. `params` and\n * `search` are **reactive accessors** (read them in a reactive scope so a\n * same-route param change updates in place, no re-mount); `children` is the\n * matched **child route** — render it wherever the nested route should appear\n * (the \"outlet\"). See ADR-0004.\n */\nexport interface RouteComponentProps {\n  /** The router instance (for `navigate`/`select`). */\n  router: Router\n  /** Reactive accessor for the current (merged) path params. */\n  params: () => Record<string, string>\n  /** Reactive accessor for the current search params. */\n  search: () => Record<string, unknown>\n  /** Reactive accessor for this route's loader state (`idle` when it has no loader). */\n  data: () => LoaderData\n  /** The matched child route (the outlet); render it to show nested routes. */\n  children: MindeesNode\n}\n\n/** A route: a path pattern, an optional component, optional search schema, and optional children. */\nexport interface RouteRecord {\n  /**\n   * The path pattern. At the top level this is absolute (`/posts/:postId`); a\n   * nested route's path is **relative to its parent** (`settings`), and a child\n   * with `''` or `'/'` is the parent's **index** route.\n   */\n  path: string\n  /** The component to render for this route. A component-less route passes its child through. */\n  component?: Component<RouteComponentProps>\n  /**\n   * A Standard Schema validating this route's search params. Its **output must\n   * be object-shaped** (search params are a record), so a non-object schema like\n   * `z.string()` is rejected at compile time and validated results need no cast.\n   *\n   * Note: only the **matched leaf** route's `searchSchema` is applied — a schema\n   * on a parent/layout route is currently not used (search is global to the URL;\n   * the leaf governs it). Per-route end-to-end `InferOutput` typing through\n   * `Router.search()` arrives with the typed route registry (a later phase).\n   */\n  searchSchema?: StandardSchemaV1<unknown, Record<string, unknown>>\n  /** Data loader for this route (sync or async); result is exposed via `data()`. */\n  loader?: LoaderFn\n  /** Declares which inputs key this route's loader cache (e.g. specific search params). */\n  loaderDeps?: LoaderDepsFn\n  /** Stale-while-revalidate window in ms; within it a successful load is reused. */\n  staleTime?: number\n  /** Nested child routes (their `path` is relative to this route). */\n  children?: readonly RouteRecord[]\n  /** Arbitrary route metadata. */\n  meta?: Readonly<Record<string, unknown>>\n}\n\n/** The result of matching a location against the route table. */\nexport interface RouteMatch {\n  /** The matched route record. */\n  route: RouteRecord\n  /** The matched pathname. */\n  pathname: string\n  /** Path params extracted from the pattern. */\n  params: Record<string, string>\n  /** Search params — validated output when a schema is present, else the raw parse. */\n  search: Record<string, unknown>\n  /** The raw parsed query, before schema validation. */\n  searchRaw: Record<string, string | string[]>\n  /** Search-validation issues, present only when validation failed. */\n  issues?: ReadonlyArray<StandardSchemaV1.Issue>\n}\n\n/** The router's reactive state — a snapshot read through fine-grained signals. */\nexport interface RouterState {\n  /** The current location. */\n  location: RouterLocation\n  /**\n   * The matched route **chain**, root → leaf (one entry per nesting level), or\n   * empty when nothing matched. Drives nested rendering ({@link createRouterView}).\n   */\n  matches: readonly RouteMatch[]\n  /** The matched **leaf** route, or `null` if nothing matched. */\n  match: RouteMatch | null\n  /** Convenience: the current pathname. */\n  pathname: string\n  /** Convenience: the current path params (`{}` when unmatched). */\n  params: Record<string, string>\n  /** Convenience: the current search params (`{}` when unmatched). */\n  search: Record<string, unknown>\n}\n\n// ---------------------------------------------------------------------------\n// Navigation types — typed targets\n// ---------------------------------------------------------------------------\n\n/** Options that apply to any navigation. */\nexport interface NavigateOptions {\n  /** Replace the current history entry instead of pushing a new one. */\n  replace?: boolean\n  /** Navigate even if the target equals the current location (skips the idempotent no-op). */\n  force?: boolean\n  /**\n   * Wrap the update in `document.startViewTransition` when available (web only).\n   * Overrides the router-level `viewTransitions` default. No-op outside a DOM.\n   */\n  viewTransition?: boolean\n}\n\n/**\n * A navigation guard. Run before each navigation with the target and current\n * hrefs. Return `false` to cancel, a string to redirect, or nothing to proceed.\n */\nexport type BeforeNavigate = (to: string, from: string) => boolean | string | undefined\n\n/** The params/search/hash carried by a structured target, with params required iff the pattern has them. */\ntype NavExtras<P extends string> = {\n  /** Search params to serialize into the query string. */\n  search?: Record<string, QueryValue>\n  /** A hash fragment (with or without a leading `#`). */\n  hash?: string\n} & (HasPathParams<P> extends true ? { params: PathParams<P> } : { params?: Record<string, never> })\n\n/**\n * A fully-typed structured navigation target. `to` is a path pattern; `params`\n * is **required** when the pattern has dynamic segments and forbidden otherwise\n * — inferred from `to` with zero codegen.\n *\n * The param requirement is enforced when `to` is a **string literal**. If `to`\n * is a widened `string` (e.g. read from a variable typed `string`), its segments\n * can't be inferred, so `params` is not type-checked — a missing required param\n * then throws {@link RouterError} (`MISSING_PARAM`) at runtime.\n *\n * @example\n * router.navigate({ to: '/posts/:postId', params: { postId: '42' } })\n * router.navigate({ to: '/about' }) // no params allowed\n */\nexport type NavTarget<P extends string> = { to: P } & NavExtras<P>\n\n/** The broad runtime shape `navigate` accepts (the typed surface is {@link NavTarget}). */\ninterface NavTargetInput {\n  to: string\n  params?: Record<string, string | number>\n  search?: Record<string, QueryValue>\n  hash?: string\n}\n\n// ---------------------------------------------------------------------------\n// Router\n// ---------------------------------------------------------------------------\n\n/** Options for {@link createRouter}. */\nexport interface CreateRouterOptions {\n  /** The route table. Order is irrelevant — routes are matched most-specific first. */\n  routes: readonly RouteRecord[]\n  /** The history adapter. Defaults to an in-memory history at `/`. */\n  history?: RouterHistory\n  /** A guard run before each navigation (cancel with `false`, redirect with a string). */\n  beforeNavigate?: BeforeNavigate\n  /** Wrap navigations in `document.startViewTransition` by default (web only). */\n  viewTransitions?: boolean\n}\n\n/** A live router instance. */\nexport interface Router {\n  /** The full reactive state snapshot. */\n  state(): RouterState\n  /** The current location. */\n  location(): RouterLocation\n  /** The matched route chain (root → leaf), or empty when unmatched. */\n  matches(): readonly RouteMatch[]\n  /** The current leaf match, or `null`. */\n  match(): RouteMatch | null\n  /** The current path params (`{}` when unmatched). */\n  params(): Record<string, string>\n  /** The current search params (`{}` when unmatched). */\n  search(): Record<string, unknown>\n  /**\n   * Subscribe to a derived slice of router state with re-render isolation. The\n   * returned accessor (a memo) only changes when `selector(state)` changes under\n   * `equals` (default `Object.is`) — the same selector-isolation technique as\n   * core's Phase 2 `createProvider` (a computed memo over an `equals:false`\n   * source), applied to route state.\n   */\n  select<S>(selector: (state: RouterState) => S, equals?: (a: S, b: S) => boolean): () => S\n  /** Navigate to a typed target or a (possibly relative) href string. */\n  navigate<P extends string>(target: string | NavTarget<P>, options?: NavigateOptions): void\n  /** Reactively read a match's loader state (`idle` when the route has no loader). */\n  loaderData(match: RouteMatch): LoaderData\n  /** Re-run the current chain's loaders (marks their cached data stale first). */\n  invalidate(): void\n  /**\n   * Run a target href's loaders WITHOUT navigating (intent prefetch). A\n   * still-in-flight preload is aborted if you then navigate to a *different*\n   * route; once it settles it warms the cache for that route's next visit\n   * (subject to `staleTime`).\n   */\n  preload(to: string): void\n  /**\n   * Replace the route table and re-match the current location **in place** — the\n   * location is preserved (dynamic reconfiguration without state reset).\n   */\n  setRoutes(routes: readonly RouteRecord[]): void\n  /**\n   * The active route table, as provided to {@link createRouter} / {@link Router.setRoutes}\n   * (the nested tree, in insertion order). Matching internally flattens the tree\n   * and orders leaves by specificity (static > dynamic > catch-all); that\n   * precedence is an implementation detail, not the shape returned here.\n   */\n  routes(): readonly RouteRecord[]\n  /** The underlying history adapter. */\n  readonly history: RouterHistory\n  /** Tear down the router's reactive scope and history subscription. */\n  dispose(): void\n}\n\nconst EMPTY_PARAMS: Record<string, string> = Object.freeze({})\nconst EMPTY_SEARCH: Record<string, unknown> = Object.freeze({})\nconst EMPTY_MATCHES: readonly RouteMatch[] = Object.freeze([])\n\n/** A leaf route flattened from the tree: its full path and its root→leaf chain. */\ninterface FlatRoute {\n  fullPath: string\n  chain: readonly RouteRecord[]\n}\n\n/** Join a parent path and a (relative) child path into a normalized full path. */\nfunction joinPaths(parent: string, child: string): string {\n  const base = parent.endsWith('/') ? parent.slice(0, -1) : parent\n  const rel = child.startsWith('/') ? child.slice(1) : child\n  if (rel.length === 0) return base.length === 0 ? '/' : base\n  return `${base}/${rel}`\n}\n\n/**\n * Flatten a (possibly nested) route tree into leaf entries, each carrying its\n * full path and the root→leaf chain of records. A route with children\n * contributes only via its children (add an index child — `path: ''` — to match\n * the parent's own path).\n */\nfunction flattenRouteTree(\n  routes: readonly RouteRecord[],\n  parentPath: string,\n  parentChain: readonly RouteRecord[],\n): FlatRoute[] {\n  const out: FlatRoute[] = []\n  for (const route of routes) {\n    const fullPath = joinPaths(parentPath, route.path)\n    const chain = [...parentChain, route]\n    if (route.children && route.children.length > 0) {\n      out.push(...flattenRouteTree(route.children, fullPath, chain))\n    } else {\n      out.push({ fullPath, chain })\n    }\n  }\n  return out\n}\n\n/** Flatten + sort a route tree most-specific first (static > dynamic > catch-all). */\nfunction compileRoutes(routes: readonly RouteRecord[]): FlatRoute[] {\n  return flattenRouteTree(routes, '', []).sort((a, b) => compareSpecificity(a.fullPath, b.fullPath))\n}\n\n/**\n * Match a location against the compiled route table, returning the matched chain\n * (root → leaf), or an empty array if nothing matched. Search is validated\n * against the **leaf** route's schema and shared across the chain.\n */\nfunction matchLocation(\n  flat: readonly FlatRoute[],\n  location: RouterLocation,\n): readonly RouteMatch[] {\n  for (const fr of flat) {\n    const params = matchPattern(fr.fullPath, location.pathname)\n    if (params === null) continue\n\n    const searchRaw = parseQuery(location.search)\n    let search: Record<string, unknown> = searchRaw\n    let issues: ReadonlyArray<StandardSchemaV1.Issue> | undefined\n\n    const leaf = fr.chain[fr.chain.length - 1]\n    if (leaf?.searchSchema) {\n      // searchSchema's output is constrained to Record<string, unknown>, so the\n      // validated value is already correctly typed — no cast needed.\n      try {\n        const result = safeValidateSearch(leaf.searchSchema, searchRaw)\n        if (result.ok) search = result.value\n        else issues = result.issues\n      } catch (err) {\n        // safeValidateSearch THROWS on an async schema (ASYNC_SCHEMA), and a\n        // schema could throw synchronously too. This runs inside matchMemo\n        // (a computed read by stateMemo AND the loader effect), so an escaping\n        // throw would poison every router-state accessor and wedge navigation.\n        // Contain it: degrade to raw search and surface it via match.issues,\n        // exactly like the invalid-input path.\n        issues = [{ message: err instanceof Error ? err.message : 'search validation failed' }]\n      }\n    }\n\n    return fr.chain.map((route) => {\n      const base: RouteMatch = { route, pathname: location.pathname, params, search, searchRaw }\n      return issues ? { ...base, issues } : base\n    })\n  }\n  return EMPTY_MATCHES\n}\n\n/**\n * Resolve a (possibly relative) path against a base pathname. Absolute paths\n * (leading `/`) ignore the base; `.`/`..` segments are applied against it,\n * treating the base pathname as a directory.\n *\n * @example\n * resolvePath('/a/b', '/x')      // '/a/b'\n * resolvePath('edit', '/posts/1') // '/posts/1/edit'\n * resolvePath('../', '/posts/1')  // '/posts'\n */\nexport function resolvePath(to: string, from: string): string {\n  const stack = to.startsWith('/') ? [] : from.split('/').filter((s) => s.length > 0)\n  for (const seg of to.split('/')) {\n    if (seg === '' || seg === '.') continue\n    if (seg === '..') stack.pop()\n    else stack.push(seg)\n  }\n  return `/${stack.join('/')}`\n}\n\n/** Resolve an href string (which may be relative and carry query/hash) against a location. */\nfunction resolveHref(to: string, from: RouterLocation): string {\n  const hasPath = to.length > 0 && to[0] !== '?' && to[0] !== '#'\n  let rest = to\n  let hash = ''\n  const hashIndex = rest.indexOf('#')\n  if (hashIndex !== -1) {\n    hash = rest.slice(hashIndex)\n    rest = rest.slice(0, hashIndex)\n  }\n  let search = ''\n  const queryIndex = rest.indexOf('?')\n  if (queryIndex !== -1) {\n    search = rest.slice(queryIndex)\n    rest = rest.slice(0, queryIndex)\n  }\n  const pathname = hasPath ? resolvePath(rest, from.pathname) : from.pathname\n  // RFC 3986: a fragment-only reference (no path, no query) keeps the current\n  // path AND query, replacing only the fragment — so a `#anchor` navigation must\n  // not drop the active search params.\n  const finalSearch = !hasPath && queryIndex === -1 ? from.search : search\n  return `${pathname}${finalSearch}${hash}`\n}\n\n/** Build an href from a structured navigation target. */\nfunction buildHref(target: NavTargetInput): string {\n  const pathname = buildPath(target.to, target.params ?? {})\n  const query = target.search ? stringifyQuery(target.search) : ''\n  let hash = target.hash ?? ''\n  if (hash.length > 0 && !hash.startsWith('#')) hash = `#${hash}`\n  return `${pathname}${query ? `?${query}` : ''}${hash}`\n}\n\n/**\n * Create a router over a route table. State is reactive (signals); call\n * {@link Router.dispose} to tear it down.\n */\nexport function createRouter(options: CreateRouterOptions): Router {\n  const history = options.history ?? createMemoryHistory()\n\n  let routesSig!: Signal<readonly RouteRecord[]>\n  let flatMemo!: Memo<FlatRoute[]>\n  let locationSig!: Signal<RouterLocation>\n  let stateMemo!: Memo<RouterState>\n  let loaders!: LoaderManager\n\n  const dispose = createRoot((disposeRoot) => {\n    routesSig = signal<readonly RouteRecord[]>(options.routes, { equals: false })\n    flatMemo = computed(() => compileRoutes(routesSig()))\n    locationSig = signal<RouterLocation>(history.location(), { equals: false })\n    const matchMemo = computed(() => matchLocation(flatMemo(), locationSig()))\n    stateMemo = computed<RouterState>(() => {\n      const location = locationSig()\n      const matches = matchMemo()\n      const leaf = matches.length > 0 ? (matches[matches.length - 1] ?? null) : null\n      return {\n        location,\n        matches,\n        match: leaf,\n        pathname: location.pathname,\n        params: leaf ? leaf.params : EMPTY_PARAMS,\n        search: leaf ? leaf.search : EMPTY_SEARCH,\n      }\n    })\n\n    // Reactive data version: bumped on any loader-cache change; loader reads\n    // subscribe to it so a component's data binding updates when its load\n    // resolves (without re-mounting the component).\n    const dataVersion = signal(0, { equals: false })\n    loaders = createLoaderManager({\n      location: () => locationSig(),\n      onChange: () => dataVersion.set(0),\n      track: () => {\n        dataVersion()\n      },\n    })\n    // Orchestrate loaders on every navigation. Owned by the router root (not a\n    // re-running region), and it never reads `dataVersion` — so no loops.\n    effect(() => loaders.sync(matchMemo()))\n\n    const unsubscribe = history.subscribe((loc) => locationSig.set(loc))\n    return () => {\n      unsubscribe()\n      loaders.dispose()\n      disposeRoot()\n    }\n  })\n\n  /** Apply the navigation guard, following redirects (capped). Returns the final href, or null to cancel. */\n  const applyGuard = (href: string): string | null => {\n    const guard = options.beforeNavigate\n    if (!guard) return href\n    let current = href\n    for (let i = 0; i < 10; i++) {\n      const result = guard(current, createHref(locationSig()))\n      if (result === false) return null\n      if (typeof result === 'string') {\n        const next = resolveHref(result, locationSig())\n        if (next === current) return current\n        current = next\n        continue\n      }\n      return current\n    }\n    // Redirect cap exceeded (a guard that keeps redirecting): cancel rather than\n    // commit a location the guard never approved.\n    return null\n  }\n\n  const navigate = (target: string | NavTargetInput, opts?: NavigateOptions): void => {\n    const initial =\n      typeof target === 'string' ? resolveHref(target, locationSig()) : buildHref(target)\n    const href = applyGuard(initial)\n    if (href === null) return\n    // Idempotent: navigating to the current location is a no-op unless forced.\n    if (opts?.force !== true && href === createHref(locationSig())) return\n\n    const commit = (): void => {\n      if (opts?.replace) history.replace(href)\n      else history.push(href)\n    }\n    const wantsTransition = opts?.viewTransition ?? options.viewTransitions ?? false\n    if (wantsTransition) startViewTransition(commit)\n    else commit()\n  }\n\n  const preload = (to: string): void => {\n    const href = resolveHref(to, locationSig())\n    loaders.preload(matchLocation(flatMemo(), parseHref(href)))\n  }\n\n  return {\n    state: () => stateMemo(),\n    location: () => locationSig(),\n    matches: () => stateMemo().matches,\n    match: () => stateMemo().match,\n    params: () => stateMemo().params,\n    search: () => stateMemo().search,\n    select: <S>(selector: (state: RouterState) => S, equals: (a: S, b: S) => boolean = Object.is) =>\n      computed(() => selector(stateMemo()), { equals }),\n    navigate: navigate as Router['navigate'],\n    loaderData: (match) => loaders.read(match),\n    invalidate: () => loaders.invalidate(stateMemo().matches),\n    preload,\n    setRoutes: (routes) => routesSig.set(routes),\n    routes: () => routesSig(),\n    history,\n    dispose,\n  }\n}\n\n/** A document that may support the View Transitions API. */\ninterface ViewTransitionDocument {\n  startViewTransition?: (callback: () => void) => unknown\n}\n\n/** The subset of a ViewTransition we touch (its eagerly-created promises). */\ninterface ViewTransitionLike {\n  ready?: Promise<unknown>\n  updateCallbackDone?: Promise<unknown>\n}\n\n/**\n * Run `commit` inside `document.startViewTransition` when available (web only),\n * else run it directly. The signals re-render is synchronous, so it happens\n * inside the transition. No-op-wrapping outside a DOM (SSR, native, tests).\n *\n * View transitions are a progressive enhancement, so this must NEVER throw out of\n * navigate() or leak an unhandled rejection: (1) a rapid second navigation aborts\n * the first transition and rejects its eagerly-created `ready`/`updateCallbackDone`\n * promises — we mark those handled; (2) some browsers throw synchronously (e.g. a\n * hidden/background document) — we fall back to a plain commit so the navigation\n * still lands (without committing twice).\n */\nfunction startViewTransition(commit: () => void): void {\n  const doc =\n    typeof document === 'undefined' ? undefined : (document as unknown as ViewTransitionDocument)\n  if (!doc?.startViewTransition) {\n    commit()\n    return\n  }\n  let committed = false\n  const runCommit = (): void => {\n    committed = true\n    commit()\n  }\n  try {\n    const transition = doc.startViewTransition(runCommit) as ViewTransitionLike | undefined\n    void transition?.ready?.catch(() => {})\n    void transition?.updateCallbackDone?.catch(() => {})\n  } catch {\n    if (!committed) commit()\n  }\n}\n\nexport { createHref }\n"],"mappings":"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"}

package/dist/search.d.ts

@@ -0,0 +1,50 @@
+import { StandardSchemaV1 } from "./standard-schema.js";
+
+//#region src/search.d.ts
+/** A value accepted when serializing a query string. */
+type QueryValue = string | number | boolean | null | undefined | ReadonlyArray<string | number | boolean>;
+/**
+ * Parse a query string into a record. Accepts an optional leading `?`. Repeated
+ * keys collapse into an array, preserving order.
+ *
+ * @example
+ * parseQuery('?page=2&tag=a&tag=b') // { page: '2', tag: ['a', 'b'] }
+ */
+declare function parseQuery(search: string): Record<string, string | string[]>;
+/**
+ * Serialize a record into a query string (no leading `?`). `null`/`undefined`
+ * values are skipped; arrays emit one `key=value` pair each. Keys are sorted for
+ * deterministic, cache-friendly output.
+ *
+ * @example
+ * stringifyQuery({ page: 2, tag: ['a', 'b'] }) // 'page=2&tag=a&tag=b'
+ */
+declare function stringifyQuery(query: Record<string, QueryValue>): string;
+/** The result of a non-throwing validation. */
+type ValidationResult<T> = {
+  readonly ok: true;
+  readonly value: T;
+} | {
+  readonly ok: false;
+  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+};
+/**
+ * Validate `input` against a Standard Schema, **without throwing** on invalid
+ * input — returns a discriminated result. Throws {@link RouterError}
+ * (`ASYNC_SCHEMA`) only for the programming error of passing an async schema,
+ * since navigation-time parsing must be synchronous.
+ */
+declare function safeValidateSearch<S extends StandardSchemaV1>(schema: S, input: unknown): ValidationResult<StandardSchemaV1.InferOutput<S>>;
+/**
+ * Validate `input` against a Standard Schema, returning the typed output or
+ * throwing {@link RouterError} (`VALIDATE_SEARCH` with the issues, or
+ * `ASYNC_SCHEMA`).
+ *
+ * @example
+ * const schema = z.object({ page: z.coerce.number() }) // Zod, Valibot, ArkType…
+ * validateSearch(schema, { page: '2' }) // { page: 2 }
+ */
+declare function validateSearch<S extends StandardSchemaV1>(schema: S, input: unknown): StandardSchemaV1.InferOutput<S>;
+//#endregion
+export { QueryValue, ValidationResult, parseQuery, safeValidateSearch, stringifyQuery, validateSearch };
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","names":[],"sources":["../src/search.ts"],"mappings":";;;;KAoBY,UAAA,kDAMR,aAAa;;;;AA+C+C;AAgBhE;;;iBAtDgB,UAAA,CAAW,MAAA,WAAiB,MAAM;;;;;;;;;iBAsClC,cAAA,CAAe,KAAA,EAAO,MAAM,SAAS,UAAA;;KAgBzC,gBAAA;EAAA,SACG,EAAA;EAAA,SAAmB,KAAA,EAAO,CAAA;AAAA;EAAA,SAC1B,EAAA;EAAA,SAAoB,MAAA,EAAQ,aAAA,CAAc,gBAAA,CAAiB,KAAA;AAAA;;;;;;;iBAQ1D,kBAAA,WAA6B,gBAAA,EAC3C,MAAA,EAAQ,CAAA,EACR,KAAA,YACC,gBAAA,CAAiB,gBAAA,CAAiB,WAAA,CAAY,CAAA;;;;;;;;;;iBAyBjC,cAAA,WAAyB,gBAAA,EACvC,MAAA,EAAQ,CAAA,EACR,KAAA,YACC,gBAAA,CAAiB,WAAA,CAAY,CAAA"}