mates-devtools 0.1.0-beta.1

package/dist/types/lib/Mutables/form/formAtom.d.ts

@@ -0,0 +1,56 @@
+import { type AtomConfig, type AtomType } from "../atom/atom";
+import type { ValidatorFn } from "./validators";
+/**
+ * Widen literal types so that `formAtom("")` infers `FormAtom<string>`
+ * instead of `FormAtom<"">`, and `formAtom(0)` infers `FormAtom<number>`
+ * instead of `FormAtom<0>`.
+ */
+type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
+/**
+ * The callable interface returned by `formAtom()`.
+ *
+ * Extends the full `AtomType<T>` contract (get, set, update, val,
+ * __subscribe, __version__, lock/unlock, toJSON, …) with form-specific
+ * members: errors, isValid, validate(), and the numeric helpers.
+ */
+export type FormAtom<T> = AtomType<T> & {
+    validate(): string[];
+    readonly errors: string[];
+    readonly isValid: boolean;
+    readonly __isFormAtom__: true;
+    toFloat(): number;
+    toFloatString(): string;
+    toValidNumber(): number;
+    readonly name: "formAtom";
+};
+/**
+ * Create a reactive form field atom.
+ *
+ * Inherits the full `AtomType<T>` interface — callable as a function,
+ * `.get()`, `.set()`, `.update()`, `.val`, `.__subscribe()`,
+ * `.__version__`, `.lock()` / `.unlock()`, `.toJSON()` — plus:
+ *
+ * - `errors`    — `string[]` reactive via an internal atom; `[]` on mount.
+ * - `isValid`   — `boolean` derived from errors.
+ * - `validate()` — run validators manually (e.g. on form submit).
+ * - `toFloat()` / `toFloatString()` / `toValidNumber()` — numeric helpers.
+ *
+ * No validation runs on mount. Every `set()` or `update()` call runs
+ * validators and updates the errors atom — one notification, one re-render.
+ * Call `validate()` manually to surface errors before the user has typed.
+ *
+ * @param initial    - The initial value.
+ * @param validators - Validator functions; each returns an error string or null.
+ *
+ * @example
+ * const name = formAtom("", [isRequired, minLength(2)]);
+ * name.set("Alice");          // runs validators, updates errors
+ * name.update(v => v.trim()); // also runs validators
+ * name("Bob");                // callable set — also runs validators
+ * name.errors;                // string[]
+ * name.isValid;               // boolean
+ * name.validate();            // force-run on submit
+ */
+export declare const formAtom: <T>(initial: T, validators?: ValidatorFn<Widen<T>>[], config?: AtomConfig) => FormAtom<Widen<T>>;
+export {};
+//# sourceMappingURL=formAtom.d.ts.map

package/dist/types/lib/Mutables/form/formAtom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formAtom.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/form/formAtom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAQ,MAAM,cAAc,CAAC;AAEpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;GAIG;AACH,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,GAC5B,MAAM,GACN,CAAC,SAAS,MAAM,GACd,MAAM,GACN,CAAC,SAAS,OAAO,GACf,OAAO,GACP,CAAC,CAAC;AAIV;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG;IACtC,QAAQ,IAAI,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,IAAI,CAAC;IAC9B,OAAO,IAAI,MAAM,CAAC;IAClB,aAAa,IAAI,MAAM,CAAC;IACxB,aAAa,IAAI,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B,CAAC;AA2FF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EACxB,SAAS,CAAC,EACV,aAAY,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAO,EACxC,SAAS,UAAU,KAClB,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAC+C,CAAC"}

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

@@ -0,0 +1,5 @@
+export * from "./formAtom";
+export * from "./transformers";
+export * from "./validateAll";
+export * from "./validators";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/form/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}

package/dist/types/lib/Mutables/form/transformers.d.ts

@@ -0,0 +1,4 @@
+export declare function toFloat(value: unknown, precision?: number): number;
+export declare function toValidNumber(value: unknown): number;
+export declare function toFloatString(value: string | number, precision?: number): string;
+//# sourceMappingURL=transformers.d.ts.map

package/dist/types/lib/Mutables/form/transformers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformers.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/form/transformers.ts"],"names":[],"mappings":"AAWA,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,GAAE,MAAU,GAAG,MAAM,CAKrE;AAiBD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIpD;AAiBD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,SAAS,GAAE,MAAU,GACpB,MAAM,CAIR"}

package/dist/types/lib/Mutables/form/validateAll.d.ts

@@ -0,0 +1,40 @@
+export interface ValidateAllResult {
+    /** `true` when every discovered FormAtom is valid. */
+    isValid: boolean;
+    /** Flat list of every error string collected across all FormAtoms. */
+    errors: string[];
+    /** Map from a human-readable key path to that field's errors. */
+    errorsByField: Record<string, string[]>;
+}
+/**
+ * Deeply walks an object or array, finds every `FormAtom` value, calls
+ * `.validate()` on each one, and returns the aggregated result.
+ *
+ * Works with:
+ * - Plain objects (recursed by key)
+ * - Arrays (recursed by index)
+ * - Nested combinations of the two
+ * - FormAtom values at any depth
+ *
+ * Non-object / non-array leaves that aren't FormAtoms are silently skipped.
+ *
+ * @example
+ * ```ts
+ * const form = {
+ *   name:    formAtom("", [isRequired]),
+ *   email:   formAtom("", [isRequired, isEmail]),
+ *   address: {
+ *     street: formAtom("", [isRequired]),
+ *     city:   formAtom("", [isRequired]),
+ *   },
+ *   tags: [formAtom("", [isRequired]), formAtom("", [isRequired])],
+ * };
+ *
+ * const { isValid, errors, errorsByField } = validateAll(form);
+ * // isValid       → false
+ * // errors        → ["Required", "Required", "Required", "Required", "Required", "Required"]
+ * // errorsByField → { "name": ["Required"], "email": ["Required"], "address.street": ["Required"], ... }
+ * ```
+ */
+export declare function validateAll(input: unknown): ValidateAllResult;
+//# sourceMappingURL=validateAll.d.ts.map

package/dist/types/lib/Mutables/form/validateAll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateAll.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/form/validateAll.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,sEAAsE;IACtE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAiD7D"}

package/dist/types/lib/Mutables/form/validators.d.ts

@@ -0,0 +1,61 @@
+export type ValidatorFn<T = any> = (value: T) => string | null;
+export declare const checkRequired: (value: unknown) => boolean;
+export declare const checkEmail: (value: string) => boolean;
+export declare const checkMinLength: (value: string, n: number) => boolean;
+export declare const checkMaxLength: (value: string, n: number) => boolean;
+export declare const checkPattern: (value: string, regex: RegExp) => boolean;
+export declare const checkMin: (value: number, n: number) => boolean;
+export declare const checkMax: (value: number, n: number) => boolean;
+export declare const checkGreaterThan: (value: number, n: number) => boolean;
+export declare const checkLessThan: (value: number, n: number) => boolean;
+export declare const checkBetween: (value: number, min: number, max: number) => boolean;
+export declare const checkDateBetween: (value: Date, min: Date, max: Date) => boolean;
+export declare const checkAfter: (value: Date, date: Date) => boolean;
+export declare const checkBefore: (value: Date, date: Date) => boolean;
+export declare const checkPast: (value: Date) => boolean;
+export declare const checkFuture: (value: Date) => boolean;
+export declare const checkInTheLast24Hours: (value: Date) => boolean;
+export declare const checkInTheNext24Hours: (value: Date) => boolean;
+export declare const checkThisCurrentMonth: (value: Date) => boolean;
+export declare const checkThisCurrentYear: (value: Date) => boolean;
+export declare const checkHasCapitalLetter: (value: string) => boolean;
+export declare const checkHasLowercaseLetter: (value: string) => boolean;
+export declare const checkHasNumber: (value: string) => boolean;
+export declare const checkHasSpecialCharacter: (value: string) => boolean;
+export declare const checkUrl: (value: string) => boolean;
+export declare const checkFloat: (value: unknown) => boolean;
+export declare const checkInteger: (value: unknown) => boolean;
+export declare const checkPositive: (value: number) => boolean;
+export declare const checkNegative: (value: number) => boolean;
+export declare const isRequired: ValidatorFn;
+export declare const isEmail: ValidatorFn<string>;
+export declare const minLength: (n: number) => ValidatorFn<string>;
+export declare const maxLength: (n: number) => ValidatorFn<string>;
+export declare const isPattern: (regex: RegExp, msg?: string) => ValidatorFn<string>;
+export declare const isMin: (n: number) => ValidatorFn<number>;
+export declare const isMax: (n: number) => ValidatorFn<number>;
+export declare const isGreaterThan: (n: number) => ValidatorFn<number>;
+export declare const isLessThan: (n: number) => ValidatorFn<number>;
+export declare const isBetween: (min: number, max: number) => ValidatorFn<number>;
+export declare const isDateBetween: (min: Date, max: Date) => ValidatorFn<Date>;
+export declare const isAfter: (date: Date) => ValidatorFn<Date>;
+export declare const isBefore: (date: Date) => ValidatorFn<Date>;
+export declare const isPast: () => ValidatorFn<Date>;
+export declare const isFuture: () => ValidatorFn<Date>;
+export declare const isInTheLast24Hours: () => ValidatorFn<Date>;
+export declare const isInTheNext24Hours: () => ValidatorFn<Date>;
+export declare const isThisCurrentMonth: () => ValidatorFn<Date>;
+export declare const isThisCurrentYear: () => ValidatorFn<Date>;
+export declare const isGoodPassword: () => ValidatorFn<string>;
+export declare const isStrongPassword: () => ValidatorFn<string>;
+export declare const isStrongestPassword: () => ValidatorFn<string>;
+export declare const hasCapitalLetter: () => ValidatorFn<string>;
+export declare const hasLowercaseLetter: () => ValidatorFn<string>;
+export declare const hasNumber: () => ValidatorFn<string>;
+export declare const hasSpecialCharacter: () => ValidatorFn<string>;
+export declare const isUrl: () => ValidatorFn<string>;
+export declare const isFloat: () => ValidatorFn<number>;
+export declare const isInteger: () => ValidatorFn<number>;
+export declare const isPositive: () => ValidatorFn<number>;
+export declare const isNegative: () => ValidatorFn<number>;
+//# sourceMappingURL=validators.d.ts.map

package/dist/types/lib/Mutables/form/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/form/validators.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,13 @@
+export * from "./atom";
+export * from "./Extended Atoms";
+export * from "./effect";
+export * from "./events";
+export * from "./form";
+export * from "./memo";
+export * from "./reactiveRunner";
+export * from "./ref";
+export * from "./scope";
+export * from "./store";
+export * from "./useState";
+export * from "./useStore";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../lib/Mutables/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,kBAAkB,CAAC;AACjC,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

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

@@ -0,0 +1,2 @@
+export * from "./memo";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/memo/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC"}

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

@@ -0,0 +1,47 @@
+import { type AtomType } from "../atom/atom";
+/**
+ * Creates a reactive computed atom whose value is derived from other atoms/stores.
+ *
+ * - Calls `fn` immediately, tracking all atoms/stores read inside it as dependencies.
+ * - Returns a reactive `AtomType<T>` atom that holds the computed value.
+ * - Whenever any dependency changes, `fn` re-runs and the returned atom is updated,
+ *   triggering its own subscribers and any component re-renders that depend on it.
+ * - The returned atom is a full `AtomType<T>` — it can be subscribed to, read as
+ *   `result()` or `result.val`, passed into templates, used inside other `memo()`/
+ *   `effect()` calls, etc.
+ * - This is a "computed" / "derived" atom pattern. It is functionally equivalent to
+ *   `atom(() => fn())` but implemented separately to avoid a circular import between
+ *   `atom` and `memo`. Prefer `atom(() => derived)` for inline derived atoms inside
+ *   components.
+ * - Correctly handles memos whose `fn` returns a function value: the function is
+ *   stored as the atom value, not called as an updater.
+ * - Must NOT be called inside a template function (restricted context guard applies
+ *   via `createReactiveRunner`).
+ *
+ * @param fn - A pure function that reads reactive dependencies and returns a derived value.
+ * @returns A reactive `AtomType<T>` atom whose value stays in sync with `fn`.
+ *
+ * @example
+ * const firstName = atom("Alice");
+ * const lastName = atom("Smith");
+ *
+ * const fullName = memo(() => `${firstName()} ${lastName()}`);
+ *
+ * fullName(); // "Alice Smith"
+ * firstName.set("Bob");
+ * fullName(); // "Bob Smith" — recomputed automatically
+ * fullName.__subscribe(() => console.log("name changed:", fullName()));
+ *
+ * @example
+ * // memo can return a function value — it is stored as-is, not called:
+ * const multiplier = atom(2);
+ * const memoFn = memo(() => {
+ *   const m = multiplier();
+ *   return (x: number) => x * m;
+ * });
+ * memoFn()(5); // 10
+ * multiplier.set(3);
+ * memoFn()(5); // 15
+ */
+export declare function memo<T>(fn: () => T): AtomType<T>;
+//# sourceMappingURL=memo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memo.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/memo/memo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAQ,MAAM,cAAc,CAAC;AAGnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CA+BhD"}

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

@@ -0,0 +1,4 @@
+export * from "./reactiveRunner";
+export * from "./trackAndSubscribe";
+export * from "./validateReactiveFunction";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/reactiveRunner/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC"}

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

@@ -0,0 +1,56 @@
+interface ReactiveRunnerOptions {
+    name: string;
+    fn: () => any;
+    onRun: (value: any) => void;
+    /** If true, fn can return a cleanup function that runs before next execution */
+    supportsCleanup?: boolean;
+}
+export declare function createReactiveRunner(options: ReactiveRunnerOptions): () => void;
+export {};
+/**
+ *
+ * const state = {count: 0};
+ * const getters = {
+ *   count() {
+ *     return state.count;
+ *   },
+ * }
+ * const setters = ({
+ *   incr() {
+ *     state.count++;
+ *   },
+ * });
+ *
+ * export const countStore = store({getters, setters});
+ *
+ * store();
+ *
+ * const st = store({
+ *  count: 0,
+ *  incr(){
+ *    this.count++;
+ *  }
+ * });
+ *
+ * st().count;
+ * st().incr();
+ *
+ * st().decr();
+ *
+ *
+ *
+ * const state = atom({count: 0, address: { street: ""}});
+ *
+ * export const getters = {
+ *   get count() {return state().count;},
+ *   get state (){return state().address.street;},
+ *   set street(value: string) {
+ *
+ *   },
+ * }
+ *
+ *  memoDirective([....keys], ()=>html``);
+ *
+ *
+ */
+//# sourceMappingURL=reactiveRunner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reactiveRunner.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/reactiveRunner/reactiveRunner.ts"],"names":[],"mappings":"AAKA,UAAU,qBAAqB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,GAAG,CAAC;IACd,KAAK,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAC5B,gFAAgF;IAChF,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,MAAM,IAAI,CA6EZ;;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG"}

package/dist/types/lib/Mutables/reactiveRunner/trackAndSubscribe.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tracks stores accessed during function execution and subscribes to them.
+ * Returns an array of unsubscribe functions.
+ */
+export declare function trackAndSubscribe(fn: () => any, onSubscribe: (store: any, runFn: () => void) => void, runFn: () => void): any;
+//# sourceMappingURL=trackAndSubscribe.d.ts.map

package/dist/types/lib/Mutables/reactiveRunner/trackAndSubscribe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackAndSubscribe.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/reactiveRunner/trackAndSubscribe.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,MAAM,GAAG,EACb,WAAW,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,IAAI,KAAK,IAAI,EACpD,KAAK,EAAE,MAAM,IAAI,GAChB,GAAG,CAmBL"}

package/dist/types/lib/Mutables/reactiveRunner/validateReactiveFunction.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Validates that a function can be used in a reactive context.
+ * Checks for async functions and nesting restrictions.
+ */
+export declare function validateReactiveFunction(name: string, fn: Function): void;
+//# sourceMappingURL=validateReactiveFunction.d.ts.map

package/dist/types/lib/Mutables/reactiveRunner/validateReactiveFunction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateReactiveFunction.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/reactiveRunner/validateReactiveFunction.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,IAAI,CAczE"}

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

@@ -0,0 +1,2 @@
+export * from "./ref";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/ref/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC"}

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

@@ -0,0 +1,74 @@
+import { ref as litRef } from "lit-html/directives/ref.js";
+export interface MatesRef<T extends Element = Element> {
+    readonly value: T | undefined;
+    __subscribe: (fn: (el: T | undefined) => void) => () => void;
+    readonly __isMatesRef__: true;
+}
+/**
+ * Creates a `MatesRef<T>` — a reactive reference that holds a DOM element,
+ * or `undefined` when no element is currently attached.
+ *
+ * The actual value is managed exclusively by the `setRef` directive; you
+ * should never call `__set` directly.
+ *
+ * @typeParam T - The element type held by this ref (defaults to `Element`).
+ *
+ * ### Members
+ * - **`value`** — the current element, or `undefined` before the element is
+ *   attached (pre-render) or after it is detached (unmount / conditional render).
+ * - **`__subscribe(fn)`** — registers a subscriber that fires synchronously
+ *   whenever `value` changes (element attached *or* detached). Returns an
+ *   unsubscribe function.
+ * - **`__isMatesRef__`** — type discriminator; always `true`. Used by
+ *   `setRef` to distinguish a `MatesRef` from a plain lit-html `Ref`.
+ *
+ * @example
+ * ```ts
+ * const inputRef = ref<HTMLInputElement>();
+ *
+ * inputRef.__subscribe((el) => {
+ *   if (el) el.focus(); // focus on mount
+ * });
+ *
+ * // In a template:
+ * html`<input ${setRef(inputRef)} type="text" />`;
+ *
+ * // After render:
+ * inputRef.value; // HTMLInputElement
+ * ```
+ */
+export declare function ref<T extends Element = Element>(): MatesRef<T>;
+/**
+ * A lit-html directive that attaches a DOM element to a `MatesRef` created by
+ * `ref()`, or forwards to a plain lit-html `Ref` / callback for backwards
+ * compatibility.
+ *
+ * ### Lifecycle behaviour
+ * - **Element added to the DOM** — `ref.value` is set to the element and all
+ *   subscribers fire synchronously.
+ * - **Element removed from the DOM** — `ref.value` is set to `undefined` and
+ *   all subscribers fire synchronously.
+ *
+ * @param r - A `MatesRef<T>` (created by `ref()`), a lit-html `Ref` object,
+ *   or a lit-html ref callback. When `r.__isMatesRef__` is `true` the
+ *   `MatesRef` path is used; otherwise the value is passed straight through
+ *   to lit-html's own `ref` directive.
+ *
+ * @example
+ * ```ts
+ * const inputRef = ref<HTMLInputElement>();
+ *
+ * inputRef.__subscribe((el) => {
+ *   if (el) el.focus(); // focus on mount
+ * });
+ *
+ * // In a template:
+ * html`<input ${setRef(inputRef)} type="text" />`;
+ *
+ * // After render:
+ * inputRef.value; // HTMLInputElement
+ * ```
+ */
+export declare function setRef<T extends Element = Element>(r: MatesRef<T> | Parameters<typeof litRef>[0]): import("lit-html/directive.js").DirectiveResult<typeof import("lit-html/directives/ref.js").RefDirective>;
+export type { MatesRef as Ref };
+//# sourceMappingURL=ref.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/ref/ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,IAAI,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAK3D,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO;IACnD,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;IAC9B,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,SAAS,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAC7D,QAAQ,CAAC,cAAc,EAAE,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAsB9D;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EAChD,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,6GAY9C;AAKD,YAAY,EAAE,QAAQ,IAAI,GAAG,EAAE,CAAC"}

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

@@ -0,0 +1,2 @@
+export * from "./scope";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/scope/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC"}

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

@@ -0,0 +1,60 @@
+type TScope<T> = T & {
+    reset: () => void;
+    __isScope___: boolean;
+};
+/**
+ * Creates a scope instance from `ScopeClass` and registers it on the current
+ * host component so child components can access it via `getParentScope`.
+ *
+ * - Instantiates `ScopeClass` in a special context (`viewOuterInProgress = true`)
+ *   so atoms and other reactive primitives can be created inside the constructor.
+ * - Walks all properties of the instance and binds non-atom methods to the instance
+ *   (`method.bind(returnObj)`), so methods work correctly when passed as callbacks.
+ * - If the instance has a `setup(propsFn)` method, calls it with the component's
+ *   props function — this allows lifecycle hooks like `onMount`/`onCleanup` to be
+ *   registered inside `setup()`.
+ * - Registers the instance on the host element's scope map so descendant components
+ *   can retrieve it via `getParentScope`.
+ * - Marks the returned object with `__isScope___: true`.
+ * - Throws if the same `ScopeClass` is used more than once in the same component.
+ *
+ * @param ScopeClass - A class whose constructor may contain atoms and reactive primitives.
+ * @returns The instantiated scope object, augmented with `__isScope___: true`.
+ *
+ * @example
+ * // In a parent component:
+ * class CounterScope {
+ *   count = atom(0);
+ *   incr() { this.count.set(this.count() + 1); }
+ *   setup(props) {
+ *     onMount(() => console.log("mounted"));
+ *   }
+ * }
+ *
+ * const counter = scope(CounterScope);
+ * counter.count(); // 0
+ * counter.incr();  // count becomes 1
+ */
+export declare const scope: <T extends object>(ScopeClass: new () => T) => TScope<T>;
+/**
+ * Retrieves a scope instance of `ScopeClass` from the nearest ancestor component
+ * that created it via `scope(ScopeClass)`.
+ *
+ * - Dispatches a bubbling `CustomEvent("request-parent-scope")` up the DOM tree.
+ * - Any ancestor host element that has the matching scope class registered will
+ *   call `detail.resolve(inst)`, providing the scope instance.
+ * - Throws an error if no ancestor has registered the requested scope class.
+ *
+ * @param ScopeClass - The class whose scope instance should be retrieved from an ancestor.
+ * @returns The scope instance registered by the nearest ancestor for `ScopeClass`.
+ * @throws If no ancestor component has a matching scope registered.
+ *
+ * @example
+ * // In a child component (ancestor must have called scope(CounterScope)):
+ * const counter = getParentScope(CounterScope);
+ * counter.count(); // reads the parent's atom
+ * counter.incr();  // mutates the parent's atom
+ */
+export declare const getParentScope: <T extends object>(ScopeClass: new () => T) => TScope<T>;
+export {};
+//# sourceMappingURL=scope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/scope/scope.ts"],"names":[],"mappings":"AAKA,KAAK,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,SAAS,MAAM,EAAE,YAAY,UAAU,CAAC,KAAG,MAAM,CAAC,CAAC,CAiEzE,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,EAC7C,YAAY,UAAU,CAAC,KACtB,MAAM,CAAC,CAAC,CAoBV,CAAC"}

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

@@ -0,0 +1,2 @@
+export * from "./store";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/store/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC"}

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

@@ -0,0 +1,73 @@
+import { type AtomType } from "../atom/atom";
+/**
+ * Mutates `stateObj` in place and returns a read-tracked wrapper around it.
+ *
+ * **Step 1 — mutate `stateObj` in place:**
+ * - Getters are redefined with version-based caching: the getter result is
+ *   recomputed only when `a.__version__` changes, avoiding redundant calls.
+ * - Methods are wrapped so that every call is automatically batched inside
+ *   `a.update()`, making method-based mutations reactive with no extra boilerplate.
+ * - Async functions are not supported and will throw.
+ *
+ * **Step 2 — build a read-tracked wrapper:**
+ * - `Object.create(stateObj)` gives the wrapper free access to all methods and
+ *   version-cached getters through the prototype chain — no need to redefine them.
+ * - Plain data properties (non-function, non-getter) get their own tracked
+ *   `get`/`set` pair on the wrapper:
+ *   - `get` calls `a()`, which registers the atom as a dependency inside
+ *     `memo()`, `effect()`, and component template functions, so they
+ *     automatically re-run when `a.update()` is called.
+ *   - `set` is a convenience shorthand: `wrapper.count = 5` is equivalent to
+ *     `a.update(s => { s.count = 5; })`.
+ * - Functions and getters are intentionally skipped on the wrapper — they are
+ *   already accessible via the prototype chain.
+ *
+ * @param stateObj    - The plain state object to wrap. Mutated in place.
+ * @param a           - The atom that holds `stateObj` and drives reactivity.
+ * @param contextName - Display name used in error messages (`"store"` / `"useState"`).
+ * @returns A read-tracked wrapper whose data-property reads subscribe the
+ *          caller to `a` as a reactive dependency.
+ */
+export declare const wrapStateFunctions: <T extends Record<string, any>>(stateObj: T, a: AtomType<T>, contextName: string) => T;
+/**
+ * Creates a global reactive state container from a plain object.
+ *
+ * Unlike `useState`, `store` is designed to be called at module level (outside
+ * any component) and shared across the application. The returned factory
+ * function can be called inside any component to obtain the shared
+ * `[wrapper, update]` pair.
+ *
+ * - `wrapper` is a read-tracked object (built by `wrapStateFunctions`):
+ *   - Reading a data property (e.g. `state.count`) subscribes the current
+ *     component / `memo` / `effect` to re-run when the store updates.
+ *   - Methods defined on the initial object are automatically wrapped to call
+ *     `a.update()` — no manual batching needed.
+ *   - Getters are version-cached and recomputed only when `a.update()` is called.
+ *   - Direct assignment (`state.count = 5`) is also reactive and equivalent to
+ *     `update(s => { s.count = 5; })`.
+ * - `update` is the raw `a.update` handle for external mutations that don't go
+ *   through a method.
+ *
+ * @param initialState - A plain object (with optional methods and getters) that
+ *                       represents the initial state of the store.
+ * @returns A factory function `() => [wrapper, update]` to be called inside
+ *          components or reactive contexts.
+ *
+ * @example
+ * // module-level — created once
+ * const counterStore = store({
+ *   count: 0,
+ *   incr() { this.count++; },
+ *   get doubled() { return this.count * 2; },
+ * });
+ *
+ * // inside a component or effect
+ * const [state, update] = counterStore();
+ *
+ * state.count;       // 0 — tracked read, component re-renders on change
+ * state.incr();      // calls a.update() automatically
+ * state.doubled;     // 0 — version-cached getter
+ * update(() => { state.count = 10; }); // direct external mutation
+ */
+export declare const store: <T extends Record<string, any>>(initialState: T) => () => (T | ((fn: (draft: T) => void, silently?: boolean) => void))[];
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/store/store.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,QAAQ,EAAQ,MAAM,cAAc,CAAC;AAkBnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9D,UAAU,CAAC,EACX,GAAG,QAAQ,CAAC,CAAC,CAAC,EACd,aAAa,MAAM,KAClB,CAyFF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,cAAc,CAAC,yEASnE,CAAC"}

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

@@ -0,0 +1,2 @@
+export * from "./useState";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../lib/Mutables/useState/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}