mates-devtools 0.1.0-beta.1

package/dist/types/lib/Mutables/useState/useState.d.ts

@@ -0,0 +1,54 @@
+type TState<T> = [T, (fn: () => void) => void];
+/**
+ * Creates local component-level reactive state from a plain object.
+ *
+ * - Must be called inside a component function (restricted context check via `atom()`).
+ * - Returns `[wrapper, update]` where:
+ *   - `wrapper` is a read-tracked proxy built by `wrapStateFunctions` — reads on data
+ *     properties automatically subscribe the component (or any enclosing `memo`/`effect`)
+ *     to re-run when the state changes.
+ *   - `update` is `a.update` — the raw handle for batched external mutations.
+ * - Methods defined on the state object are automatically wrapped to call `a.update()`
+ *   internally, so calling a method (e.g. `state.incr()`) triggers reactivity without
+ *   needing to call `update()` manually.
+ * - Direct property assignment on `wrapper` also triggers reactivity:
+ *   `wrapper.count = 5` is equivalent to `update(s => { s.count = 5; })`.
+ * - The state instance is registered on `host._useStates` for devtools inspection.
+ *
+ * @param stateObj - A plain object (with optional methods and getters) that defines
+ *                   the initial state shape.
+ * @returns A tuple `[wrapper, update]`.
+ *
+ * @example
+ * // 1. Using update() explicitly with inline mutations:
+ * const counter = (props: PropsType<{}>) => {
+ *   const [state, update] = useState({ count: 0 });
+ *
+ *   return html`
+ *     <div>
+ *       <p>Count: ${state.count}</p>
+ *       <button @click=${() => update(() => { state.count++; })}>+</button>
+ *     </div>
+ *   `;
+ * };
+ *
+ * @example
+ * // 2. Using methods on the state object (no explicit update() needed):
+ * const counter = (props: PropsType<{}>) => {
+ *   const [state] = useState({
+ *     count: 0,
+ *     incr() { this.count++; },
+ *     get doubled() { return this.count * 2; },
+ *   });
+ *
+ *   return html`
+ *     <div>
+ *       <p>Count: ${state.count} (doubled: ${state.doubled})</p>
+ *       <button @click=${state.incr}>+</button>
+ *     </div>
+ *   `;
+ * };
+ */
+export declare const useState: <T extends object>(stateObj: T) => TState<T>;
+export {};
+//# sourceMappingURL=useState.d.ts.map

package/dist/types/lib/Mutables/useState/useState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useState.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/useState/useState.ts"],"names":[],"mappings":"AAIA,KAAK,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,MAAM,EAAE,UAAU,CAAC,KAAG,MAAM,CAAC,CAAC,CAehE,CAAC"}

package/dist/types/lib/Mutables/useStore/hostContext.d.ts

@@ -0,0 +1,13 @@
+import type { HostElement } from "../../Template/x-x.types";
+export declare function withHost(host: HostElement, renderFn: (...args: any[]) => any): any;
+/**
+ * Get the current host element (XX custom element instance)
+ *
+ * Returns the XX custom element instance with all its runtime properties
+ * including _setupStack, _setupIndex, state, cleanups, scopes, etc.
+ *
+ * @param throwError - Whether to throw an error if no host is found (default: true)
+ * @returns The current host element, or null if not found and throwError is false
+ */
+export declare function getCurrentHost(throwError?: boolean): HostElement | null;
+//# sourceMappingURL=hostContext.d.ts.map

package/dist/types/lib/Mutables/useStore/hostContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostContext.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/useStore/hostContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAI5D,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,OAS5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CASvE"}

package/dist/types/lib/Mutables/useStore/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./hostContext";
+export * from "./lifecycle";
+export * from "./onError";
+export * from "./onReferenceChange";
+export * from "./safetyCheck";
+export * from "./setter";
+export * from "./subscription";
+export * from "./useContext";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/Mutables/useStore/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/useStore/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC"}

package/dist/types/lib/Mutables/useStore/lifecycle.d.ts

@@ -0,0 +1,94 @@
+type CleanupFn = () => void;
+type MountFn = (() => CleanupFn | undefined | void) | (() => Promise<void>);
+/**
+ * Runs `fn` once after the component's DOM is attached and ready
+ * (fires on the internal `DOMReadyEvent`).
+ *
+ * Accepts both sync and async functions.
+ *
+ * **Sync behaviour:**
+ * `fn` runs after the component's DOM is ready. If `fn` returns a function,
+ * that function is registered as a cleanup and called when the component unmounts.
+ *
+ * **Async behaviour — client:**
+ * `fn` is called after `DOMReadyEvent` fires (same timing as sync).
+ * State updates inside `fn` trigger reactive re-renders normally.
+ * Cleanup return values are not supported for async functions (a `Promise`
+ * is returned, not a `CleanupFn`).
+ *
+ * **Async behaviour — SSR:**
+ * `DOMReadyEvent` is a no-op on the server's fake host, so async functions
+ * would otherwise never run. Instead, when `isSSR()` is `true`, async functions
+ * are pushed onto `host._asyncMountQueue`. The renderer drains this queue
+ * (`await Promise.all`) **before** calling the template function, so by the
+ * time the HTML is serialized the state is already populated.
+ * Sync functions are silently ignored on the server (same as before —
+ * `DOMReadyEvent.__subscribe` is a no-op on the fake host).
+ *
+ * Must be called in the component outer function (guarded by `safetyCheck`).
+ *
+ * @example
+ * // Sync — return a cleanup function to run on unmount:
+ * onMount(() => {
+ *   console.log("component mounted");
+ *   return () => console.log("component unmounted");
+ * });
+ *
+ * // Async — no cleanup return value supported:
+ * onMount(async () => {
+ *   const data = await fetch("/api/init").then(r => r.json());
+ *   myAtom.set(data);
+ * });
+ */
+export declare const onMount: (fn: MountFn) => void;
+/**
+ * Runs `fn` after each paint of the current component and all its children,
+ * during both the initial mount and every subsequent update cycle.
+ *
+ * If `fn` returns a function, that function is registered as a cleanup and
+ * called before the next paint or when the component unmounts.
+ *
+ * Must be called in the component outer function (guarded by `safetyCheck`).
+ *
+ * @example
+ * onPaint(() => {
+ *   console.log("painted");
+ *   return () => console.log("paint cleanup");
+ * });
+ */
+export declare const onPaint: (fn: () => CleanupFn | undefined) => void;
+/**
+ * Runs `fn` once, after the current component **and all its children** have
+ * mounted, before the next paint.
+ *
+ * Uses `globalScheduler.onceIdle` — `fn` fires when the scheduler becomes idle,
+ * guaranteeing that the entire component subtree is fully mounted.
+ *
+ * If `fn` returns a function, that function is registered as a cleanup and
+ * called when the component unmounts.
+ *
+ * Must be called in the component outer function (guarded by `safetyCheck`).
+ *
+ * @example
+ * onAllMount(() => {
+ *   console.log("current component and all children are mounted");
+ * });
+ */
+export declare const onAllMount: (fn: () => CleanupFn | undefined) => void;
+/**
+ * Registers `fn` to run when the component is unmounted (removed from the DOM).
+ *
+ * Equivalent to returning a cleanup function from `onMount`, but can be called
+ * independently at any point in the component outer function.
+ *
+ * Must be called in the component outer function (guarded by `safetyCheck`).
+ *
+ * @example
+ * onCleanup(() => {
+ *   console.log("component unmounted — cleaning up");
+ *   subscription.unsubscribe();
+ * });
+ */
+export declare const onCleanup: (fn: () => void) => void;
+export {};
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/types/lib/Mutables/useStore/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/useStore/lifecycle.ts"],"names":[],"mappings":"AAKA,KAAK,SAAS,GAAG,MAAM,IAAI,CAAC;AAC5B,KAAK,OAAO,GAAG,CAAC,MAAM,SAAS,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAI5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,OAAO,GAAI,IAAI,OAAO,SAwClC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,OAAO,GAAI,IAAI,MAAM,SAAS,GAAG,SAAS,SAStD,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,UAAU,GAAI,IAAI,MAAM,SAAS,GAAG,SAAS,SAazD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,GAAI,IAAI,MAAM,IAAI,SAKvC,CAAC"}

package/dist/types/lib/Mutables/useStore/onError.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Register an error handler for the current component.
+ *
+ * Called in the outer function. When the component's outer function or
+ * template function throws during render, every registered handler
+ * receives the error object. The handler does not return anything —
+ * the component renders nothing in production or a dev error message
+ * in development.
+ *
+ * @example
+ * ```ts
+ * const MyComponent: ComponentFn<{}> = () => {
+ *   onError((error) => {
+ *     reportToSentry(error);
+ *   });
+ *   return () => html`<div>${riskyStuff()}</div>`;
+ * };
+ * ```
+ */
+export declare const onError: (fn: (error: unknown) => void) => void;
+//# sourceMappingURL=onError.d.ts.map

package/dist/types/lib/Mutables/useStore/onError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onError.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/useStore/onError.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,OAAO,GAAI,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,SAKnD,CAAC"}

package/dist/types/lib/Mutables/useStore/onReferenceChange.d.ts

@@ -0,0 +1,2 @@
+export declare const onReferenceChange: (effect: () => void, deps: () => any[]) => void;
+//# sourceMappingURL=onReferenceChange.d.ts.map

package/dist/types/lib/Mutables/useStore/onReferenceChange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onReferenceChange.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/useStore/onReferenceChange.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,IAAI,EAAE,MAAM,MAAM,GAAG,EAAE,SAgBtE,CAAC"}

package/dist/types/lib/Mutables/useStore/safetyCheck.d.ts

@@ -0,0 +1,2 @@
+export declare const safetyCheck: () => void;
+//# sourceMappingURL=safetyCheck.d.ts.map

package/dist/types/lib/Mutables/useStore/safetyCheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safetyCheck.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/useStore/safetyCheck.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,YASvB,CAAC"}

package/dist/types/lib/Mutables/useStore/setter.d.ts

@@ -0,0 +1,52 @@
+import type { SetterReturnType } from "./subscription";
+/**
+ * Wraps a function in a reactive setter that, when called:
+ *  1. Invokes the underlying function `fn` with any forwarded arguments.
+ *  2. Notifies all subscribers (scheduled via `effectScheduler`).
+ *  3. Schedules the host component for re-render (via `globalScheduler`).
+ *
+ * **Allowed call sites** — must be called in one of:
+ * - A component outer function
+ * - A `scope` class body (as a class property)
+ * - `useState`
+ * - A `view` component's outer function
+ *
+ * Cannot be created inside a template function (restricted context guard) or
+ * inside a `setup()` method.
+ *
+ * @param fn - The function to wrap. Its signature is preserved when the setter
+ *   is invoked.
+ * @param doSafetyCheck - When `true` (default), enforces the call-site guard
+ *   and the `setup()` restriction. Pass `false` only in advanced / internal
+ *   scenarios where the guard is intentionally bypassed.
+ * @returns A callable `SetterReturnType` that forwards calls to `fn` and
+ *   exposes the following extra members:
+ *   - `__subscribe(fn)` — registers a zero-argument callback that fires
+ *     (via `effectScheduler`) every time the setter is called; returns an
+ *     unsubscribe function.
+ *   - `__version__` — read-only numeric version counter (currently always `0`;
+ *     reserved for future change-detection use).
+ *   - `__isSetter___` — `true`; type/identity discriminator.
+ *   - `set(newFn)` — swaps the underlying function without replacing the
+ *     setter reference; useful for hot-reloading or derived setters.
+ *
+ * @example
+ * ```ts
+ * // Inside a component outer function or scope class:
+ * const count = atom(0);
+ * const incr = setter(() => count.set(count() + 1));
+ *
+ * incr();                   // calls fn, notifies subscribers, schedules re-render
+ * incr.__subscribe(() => console.log("incr called")); // fires on every call
+ * incr.__isSetter___;       // true
+ * incr.set(() => count.set(count() + 10)); // swap underlying fn
+ *
+ * // $ and _ are identical aliases:
+ * const decr  = $(() => count.set(count() - 1));
+ * const reset = _(() => count.set(0));
+ * ```
+ */
+export declare const setter: <T extends (...args: any[]) => any>(fn: T, doSafetyCheck?: boolean) => SetterReturnType<Function>;
+export declare const $: <T extends (...args: any[]) => any>(fn: T, doSafetyCheck?: boolean) => SetterReturnType<Function>;
+export declare const _: <T extends (...args: any[]) => any>(fn: T, doSafetyCheck?: boolean) => SetterReturnType<Function>;
+//# sourceMappingURL=setter.d.ts.map

package/dist/types/lib/Mutables/useStore/setter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setter.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/useStore/setter.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACtD,IAAI,CAAC,EACL,gBAAe,OAAc,KAC5B,gBAAgB,CAAC,QAAQ,CAoD3B,CAAC;AAEF,eAAO,MAAM,CAAC,GAzDS,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,MAClD,CAAC,kBACU,OAAO,KACrB,gBAAgB,CAAC,QAAQ,CAsDL,CAAC;AACxB,eAAO,MAAM,CAAC,GA1DS,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,MAClD,CAAC,kBACU,OAAO,KACrB,gBAAgB,CAAC,QAAQ,CAuDL,CAAC"}

package/dist/types/lib/Mutables/useStore/subscription.d.ts

@@ -0,0 +1,50 @@
+export declare function _subToView(store: any, throwError?: boolean, subscribeFn?: (fn: () => void) => () => void): void;
+/**
+ * Subscribable type - any function or object that has subscribe or __subscribe method
+ *
+ * This type is compatible with:
+ * - Mates stores (atoms, setters, etc.) - use `__subscribe`
+ * - Zustand stores - use `subscribe`
+ * - Redux stores - use `subscribe`
+ * - Any custom store with a subscribe method
+ */
+export type Subscribable = {
+    subscribe?: (listener: () => void) => Function;
+    __subscribe?: (listener: () => void) => Function;
+    [key: string]: any;
+};
+/**
+ * Subscribe to a store and trigger re-renders when it changes
+ *
+ * Works with:
+ * - Mates stores (atoms, setters, getters, etc.)
+ * - Zustand stores
+ * - Redux stores
+ * - Any store with a `subscribe` or `__subscribe` method
+ *
+ * @param store - Any subscribable store
+ * @returns The same store (for chaining)
+ *
+ * @example
+ * ```ts
+ * // Mates atom
+ * const count = atom(0);
+ * useStore(count);
+ *
+ * // Zustand store
+ * const useZustandStore = create((set) => ({ count: 0 }));
+ * useStore(useZustandStore);
+ *
+ * // Redux store
+ * useStore(reduxStore);
+ * ```
+ */
+export declare function useStore<T extends Subscribable>(store: T): T;
+export type SetterReturnType<T extends Function> = T & {
+    __subscribe: (listener: () => void) => Function;
+    __version__: number;
+    set: SetterReturnType<T>;
+    [key: string]: any;
+};
+export declare const on: (callback: () => (() => void) | undefined, deps: any[]) => () => void;
+//# sourceMappingURL=subscription.d.ts.map

package/dist/types/lib/Mutables/useStore/subscription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/useStore/subscription.ts"],"names":[],"mappings":"AAMA,wBAAgB,UAAU,CACxB,KAAK,EAAE,GAAG,EACV,UAAU,UAAO,EACjB,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,QAY7C;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,QAAQ,CAAC;IAC/C,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,QAAQ,CAAC;IACjD,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,YAAY,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAG5D;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,QAAQ,IAAI,CAAC,GAAG;IACrD,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,QAAQ,CAAC;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB,CAAC;AAEF,eAAO,MAAM,EAAE,GAAI,UAAU,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,EAAE,MAAM,GAAG,EAAE,eAyCvE,CAAC"}

package/dist/types/lib/Mutables/useStore/useContext.d.ts

@@ -0,0 +1,3 @@
+import type Context from "../../Utils/Context";
+export declare function useContext<T>(context: Context<T>): T;
+//# sourceMappingURL=useContext.d.ts.map

package/dist/types/lib/Mutables/useStore/useContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useContext.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/useStore/useContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAC;AAG/C,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAgBpD"}

package/dist/types/lib/Mutables/useStore/useStore.d.ts

@@ -0,0 +1,7 @@
+export { getCurrentHost, withHost } from "./hostContext";
+export { onAllMount, onCleanup, onMount, onPaint } from "./lifecycle";
+export { safetyCheck } from "./safetyCheck";
+export { _, setter } from "./setter";
+export { _subToView, type SetterReturnType, type Subscribable, useStore, } from "./subscription";
+export { useContext } from "./useContext";
+//# sourceMappingURL=useStore.d.ts.map

package/dist/types/lib/Mutables/useStore/useStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStore.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/useStore/useStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EACL,UAAU,EACV,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,QAAQ,GACT,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/types/lib/Router/Router.d.ts

@@ -0,0 +1,54 @@
+import { nothing } from "lit-html";
+import type { ComponentType, View } from "../Template/x-x.types";
+/**
+ * Renders `view` if the current URL path matches `path`; otherwise returns `null`.
+ *
+ * Uses `isPathMatching` from `pathResolver` for pattern matching, making it
+ * SSR-safe and consistent with the rest of the Router module.
+ *
+ * @param path   - The path pattern to match against the current URL pathname.
+ * @param options - Object containing a `view` factory function to render on match.
+ * @returns The result of `view()` when the path matches, or `null` when it does not.
+ *
+ * @example
+ * // Inside a template function:
+ * ${route("/about", { view: () => html`<about-page></about-page>` })}
+ */
+export declare const route: (path: string, { view: viewFn }: {
+    view: View;
+}) => typeof nothing | import("lit-html").TemplateResult<1> | null;
+type RouteConfig = {
+    path: string;
+    component: ComponentType;
+};
+/**
+ * Creates a router that matches the current URL path against `routeConfig` in
+ * order and returns a factory function that renders the first matching route.
+ *
+ * Supports both **eager** components (`Component`) and **lazy** components
+ * (`async () => import("...")`). Lazy components are passed directly to `x()`,
+ * which forwards them to the `x-view` element's view setter — the built-in
+ * `isAsyncValue` / `resolveAsyncValue` / `unwrapModule` pipeline handles
+ * resolution transparently.
+ *
+ * If no route matches and `NotFound` is provided, renders `NotFound`;
+ * otherwise renders `nothing`.
+ *
+ * @param routeConfig - Ordered array of `{ path, component }` entries.
+ * @param NotFound    - Optional component rendered when no route matches.
+ * @returns A factory function whose return value can be rendered directly
+ *          with lit-html's `render()`.
+ *
+ * @example
+ * const appRouter = Router([
+ *   { path: "/",      component: HomePage },
+ *   { path: "/about", component: async () => import("./AboutPage") },
+ *   { path: "/users", component: UsersPage },
+ * ], NotFoundPage);
+ *
+ * // In template:
+ * ${appRouter()}
+ */
+export declare const Router: (routeConfig: RouteConfig[], NotFound?: ComponentType) => (() => symbol) | (() => import("lit-html").TemplateResult<1>);
+export {};
+//# sourceMappingURL=Router.d.ts.map

package/dist/types/lib/Router/Router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Router.d.ts","sourceRoot":"","sources":["../../../../../lib/Router/Router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,KAAK,EAAa,aAAa,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAI5E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,EAAE,kBAAkB;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,iEAGnE,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,aAAa,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,MAAM,GACjB,aAAa,WAAW,EAAE,EAC1B,WAAW,aAAa,kEAuBzB,CAAC"}

package/dist/types/lib/Router/animatedRouter.d.ts

@@ -0,0 +1,48 @@
+import type { AnimationPreset } from "../actions/animateTypes";
+import type { ComponentType } from "../Template/x-x.types";
+export interface AnimatedRouteConfig {
+    path: string;
+    component: ComponentType;
+    props?: Record<string, any>;
+    enter?: AnimationPreset;
+    exit?: AnimationPreset;
+}
+export interface AnimatedRouterOptions {
+    notFound?: ComponentType;
+    enter?: AnimationPreset;
+    exit?: AnimationPreset;
+}
+export { animateContainer, nextFrame } from "../actions/animateSwap";
+/**
+ * Animated client-side router with exit → swap → enter transitions.
+ *
+ * Matches the current URL (`pathAtom`) against `routes` in order and renders
+ * the first match. When the matched route changes, the old component plays
+ * its exit animation, the new component is mounted, and the enter animation
+ * plays.
+ *
+ * ### Scroll behaviour
+ *
+ * The router does **not** manage scroll position — following the same
+ * philosophy as React Router, which treats scroll as an application-level
+ * concern rather than a router concern.
+ *
+ * If you want scroll-to-top on navigation, handle it in your app code
+ * (e.g. via `onNavigate`):
+ *
+ * ```ts
+ * onNavigate(() => window.scrollTo(0, 0));
+ * ```
+ *
+ * ### Nested / child routers
+ *
+ * `animatedRouter` can be used inside a component that is itself rendered
+ * by another `animatedRouter` (child routes). When a child route changes
+ * but the parent route stays the same, only the **child** router swaps —
+ * the parent sees the same route object and does nothing.
+ *
+ * @param routes  - Ordered array of `{ path, component, enter?, exit? }`.
+ * @param options - Global enter/exit presets and notFound fallback.
+ */
+export declare function animatedRouter(routes: AnimatedRouteConfig[], options?: AnimatedRouterOptions): import("lit-html").TemplateResult<1>;
+//# sourceMappingURL=animatedRouter.d.ts.map

package/dist/types/lib/Router/animatedRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animatedRouter.d.ts","sourceRoot":"","sources":["../../../../../lib/Router/animatedRouter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAM/D,OAAO,KAAK,EAAE,aAAa,EAAS,MAAM,uBAAuB,CAAC;AAIlE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,aAAa,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB;AAGD,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAuFrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,mBAAmB,EAAE,EAC7B,OAAO,GAAE,qBAA0B,wCAGpC"}

package/dist/types/lib/Router/buildPath.d.ts

@@ -0,0 +1,20 @@
+type IdStart = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "_";
+type IdRest = IdStart | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+type TakeIdRest<S extends string> = S extends `${infer C}${infer R}` ? C extends IdRest ? `${C}${TakeIdRest<R>}` : "" : "";
+type TakeIdentifier<S extends string> = S extends `${infer C}${infer R}` ? C extends IdStart ? `${C}${TakeIdRest<R>}` : "" : "";
+type ExtractParams<Path extends string> = Path extends `${infer _Start}:${infer Param}/${infer Rest}` ? TakeIdentifier<Param> extends "" ? ExtractParams<Rest> : {
+    [K in TakeIdentifier<Param> | keyof ExtractParams<Rest>]: string | number | boolean;
+} : Path extends `${infer _Start}:${infer Param}` ? TakeIdentifier<Param> extends "" ? never : {
+    [K in TakeIdentifier<Param>]: string | number | boolean;
+} : never;
+type BuildPathArgs<Path extends string> = ExtractParams<Path> extends never ? [path: Path, params?: undefined] : [path: Path, params: ExtractParams<Path>];
+/**
+ * Build a concrete path from a route pattern with optional dynamic segments.
+ *
+ * @example
+ * buildPath("/users/:id", { id: 42 }) // "/users/42"
+ * buildPath("/posts/:postId/comments/:commentId", { postId: 1, commentId: 7 })
+ */
+export declare function buildPath<Path extends string>(...args: BuildPathArgs<Path>): string;
+export {};
+//# sourceMappingURL=buildPath.d.ts.map

package/dist/types/lib/Router/buildPath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildPath.d.ts","sourceRoot":"","sources":["../../../../../lib/Router/buildPath.ts"],"names":[],"mappings":"AAEA,KAAK,OAAO,GACR,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,CAAC;AACR,KAAK,MAAM,GACP,OAAO,GACP,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,CAAC;AACR,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,GAChE,CAAC,SAAS,MAAM,GACd,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,GACtB,EAAE,GACJ,EAAE,CAAC;AACP,KAAK,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,GACpE,CAAC,SAAS,OAAO,GACf,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,GACtB,EAAE,GACJ,EAAE,CAAC;AAEP,KAAK,aAAa,CAAC,IAAI,SAAS,MAAM,IACpC,IAAI,SAAS,GAAG,MAAM,MAAM,IAAI,MAAM,KAAK,IAAI,MAAM,IAAI,EAAE,GACvD,cAAc,CAAC,KAAK,CAAC,SAAS,EAAE,GAC9B,aAAa,CAAC,IAAI,CAAC,GACnB;KACG,CAAC,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,GACnD,MAAM,GACN,MAAM,GACN,OAAO;CACZ,GACH,IAAI,SAAS,GAAG,MAAM,MAAM,IAAI,MAAM,KAAK,EAAE,GAC3C,cAAc,CAAC,KAAK,CAAC,SAAS,EAAE,GAC9B,KAAK,GACL;KAAG,CAAC,IAAI,cAAc,CAAC,KAAK,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO;CAAE,GAC7D,KAAK,CAAC;AAEd,KAAK,aAAa,CAAC,IAAI,SAAS,MAAM,IACpC,aAAa,CAAC,IAAI,CAAC,SAAS,KAAK,GAC7B,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,SAAS,CAAC,GAChC,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;AAEhD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,SAAS,MAAM,EAC3C,GAAG,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,GAC3B,MAAM,CAUR"}

package/dist/types/lib/Router/hashAtom.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Singleton atom holding the current URL hash fragment as a parsed object.
+ *
+ * Hydrated from `window.location.hash` at module load time.  All reads are
+ * reactive — any effect or component that calls `hashAtom()` will re-run
+ * whenever the hash state changes.
+ *
+ * Setting the atom via `hashAtom.set(obj)` automatically serialises the new
+ * value back to the URL hash using `history.replaceState`.
+ */
+export declare const hashAtom: import("..").AtomType<Record<string, any>>;
+//# sourceMappingURL=hashAtom.d.ts.map

package/dist/types/lib/Router/hashAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashAtom.d.ts","sourceRoot":"","sources":["../../../../../lib/Router/hashAtom.ts"],"names":[],"mappings":"AA+FA;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,4CAAqC,CAAC"}

package/dist/types/lib/Router/index.d.ts

@@ -0,0 +1,11 @@
+export { type AnimatedRouteConfig, type AnimatedRouterOptions, animatedRouter, } from "./animatedRouter";
+export { buildPath } from "./buildPath";
+export { hashAtom } from "./hashAtom";
+export { isPathMatching } from "./isPathMatching";
+export { location } from "./location";
+export { navigateTo } from "./navigateTo";
+export { lockNavigation, navigationLocked, unlockNavigation, } from "./navigationLock";
+export { pathAtom } from "./pathAtom";
+export { qsAtom } from "./qsAtom";
+export { Router, route } from "./Router";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../lib/Router/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC"}

package/dist/types/lib/Router/isPathMatching.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Checks whether the current pathname matches a route pattern.
+ *
+ * Supports dynamic params in the pattern using `:param` segments.
+ *
+ * @example
+ * // current path: /users/42
+ * isPathMatching("/users/:id") // true
+ * isPathMatching("/users")     // false
+ */
+export declare const isPathMatching: (path: string) => boolean;
+//# sourceMappingURL=isPathMatching.d.ts.map

package/dist/types/lib/Router/isPathMatching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isPathMatching.d.ts","sourceRoot":"","sources":["../../../../../lib/Router/isPathMatching.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAuB7C,CAAC"}

package/dist/types/lib/Router/location.d.ts

@@ -0,0 +1,74 @@
+export { lockNavigation, navigationLocked, unlockNavigation, } from "./navigationLock";
+/**
+ * Read-only facade over the three URL-state atoms: `pathAtom`, `hashAtom`,
+ * and `qsAtom`.
+ *
+ * Every getter performs a **tracked read**, so any reactive context (effect,
+ * component render function) that accesses one of these properties will
+ * automatically re-run when that part of the URL changes.
+ *
+ * This module also re-exports `navigationLocked`, `lockNavigation`, and
+ * `unlockNavigation` from `navigationLock.ts` as a single convenient import
+ * point for consumers that need both location data and navigation control.
+ *
+ * **Intentionally read-only.** To navigate, use `navigateTo()`. To update
+ * the query string or hash state, use `qsAtom.set()` / `hashAtom.set()`.
+ *
+ * @example
+ * import { location } from "mates";
+ *
+ * location.path;   // "/about"          — current pathname
+ * location.hash;   // { tab: "overview" } — parsed hash fragment
+ * location.qsObj;  // { q: "react", page: 1 } — parsed query string
+ *
+ * @example
+ * import { location, lockNavigation, unlockNavigation } from "mates";
+ *
+ * lockNavigation();
+ * navigateTo("/somewhere"); // no-op while locked
+ * unlockNavigation();
+ * navigateTo("/somewhere"); // works
+ */
+export declare const location: {
+    /**
+     * The current URL pathname (e.g. `"/about"`), sourced from `pathAtom`.
+     *
+     * Reading this property inside a reactive context registers a dependency on
+     * `pathAtom`, so the context re-runs whenever the path changes.
+     *
+     * @example
+     * location.path; // "/about"
+     */
+    readonly path: string;
+    /**
+     * The current URL hash fragment as a parsed plain object, sourced from
+     * `hashAtom`.
+     *
+     * The hash is parsed as `URLSearchParams` — primitive values are strings,
+     * JSON-encoded objects/arrays are automatically deserialised.
+     *
+     * Reading this property inside a reactive context registers a dependency on
+     * `hashAtom`, so the context re-runs whenever the hash state changes.
+     *
+     * @example
+     * // URL: #tab=overview&page=2
+     * location.hash; // { tab: "overview", page: "2" }
+     */
+    readonly hash: Record<string, any>;
+    /**
+     * The current URL query string as a parsed plain object, sourced from
+     * `qsAtom`.
+     *
+     * The query string is parsed via `URLSearchParams` — primitive values are
+     * strings, JSON-encoded objects/arrays are automatically deserialised.
+     *
+     * Reading this property inside a reactive context registers a dependency on
+     * `qsAtom`, so the context re-runs whenever the query string changes.
+     *
+     * @example
+     * // URL: ?q=react&page=1
+     * location.qsObj; // { q: "react", page: "1" }
+     */
+    readonly qsObj: Record<string, any>;
+};
+//# sourceMappingURL=location.d.ts.map

package/dist/types/lib/Router/location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"location.d.ts","sourceRoot":"","sources":["../../../../../lib/Router/location.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,QAAQ;IACnB;;;;;;;;OAQG;mBACS,MAAM;IAIlB;;;;;;;;;;;;;OAaG;mBACS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAI/B;;;;;;;;;;;;;OAaG;oBACU,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAGjC,CAAC"}