@sladg/apex-state 3.7.1 → 3.9.0

package/dist/deep-clone-DMRvv0Pr.d.ts

@@ -0,0 +1,2119 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Hash key type for Record-based paths
+ *
+ * Use in template strings to construct paths through Record/HashMap properties.
+ * This type represents the literal string '[*]' used for indexing into Records.
+ *
+ * @example
+ * ```typescript
+ * type Path = `users.${HASH_KEY}.name` // "users.[*].name"
+ * ```
+ */
+type HASH_KEY = '[*]';
+
+/**
+ * DeepKey utility type
+ *
+ * Generates a union of all possible dot-notation paths for nested objects.
+ * Supports nested objects up to depth 20 to handle deeply nested data structures.
+ * Handles arrays and complex object hierarchies.
+ *
+ * Uses loop unrolling: processes 2 nesting levels per recursion call,
+ * halving recursion depth while preserving bottom-up evaluation that
+ * TypeScript can cache (no prefix parameter).
+ *
+ * Examples of supported paths:
+ * - Simple: "name", "email"
+ * - Nested: "user.address.street"
+ * - Deep: "g.p.data.optionsCommon.base.ccyPair.forCurrency.id" (11 levels)
+ *
+ * @example
+ * ```typescript
+ * type User = {
+ *   name: string
+ *   address: {
+ *     street: string
+ *     city: string
+ *   }
+ * }
+ *
+ * // DeepKey<User> = "name" | "address" | "address.street" | "address.city"
+ * ```
+ *
+ * @example Custom depth — reduce for faster compilation on wide types
+ * ```typescript
+ * // Only traverse 10 levels deep instead of the default 20
+ * type ShallowPaths = DeepKey<User, 10>
+ * ```
+ *
+ * @example Depth limit marker — `??` appears at the cutoff point
+ * ```typescript
+ * // If a type is nested deeper than Depth, autocomplete shows:
+ * // "some.deep.path.??" — signaling you should increase depth or restructure
+ * type Paths = DeepKey<VeryDeepType, 6>
+ * ```
+ */
+
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+type IsAny$1<T> = 0 extends 1 & T ? true : false;
+/**
+ * Default recursion depth for DeepKey and all types that depend on it.
+ * Change this single value to adjust the depth limit across the entire type system.
+ *
+ * Propagates to: SyncPair, FlipPair, AggregationPair, ComputationPair,
+ * BoolLogic, SideEffects, DeepKeyFiltered, ClearPathRule.
+ *
+ * @example Override per-call instead of changing the default
+ * ```typescript
+ * type Shallow = DeepKey<MyState, 10>    // reduced depth
+ * type Deeper = DeepKey<MyState, 30>     // increased depth
+ * ```
+ */
+type DefaultDepth = 20;
+/**
+ * Marker emitted when DeepKey reaches its depth limit on an object type,
+ * or when it encounters an `any`-typed property (unknowable structure).
+ * Appears as `some.deep.path.??` in autocomplete, signaling the cutoff point.
+ * Users seeing this can increase depth: `DeepKey<T, 30>` or restructure their type.
+ */
+type DepthLimitMarker = '??';
+type DeepKey<T, Depth extends number = DefaultDepth> = DeepKeyUnrolled<T, Depth> & string;
+/**
+ * DeepKey with `??` marker paths excluded. Use in types that resolve path values
+ * (DeepValue, DeepKeyFiltered, PathsWithSameValueAs) where `??` would fail resolution.
+ * DeepKey itself keeps `??` for IDE autocomplete visibility.
+ */
+type ResolvableDeepKey<T, Depth extends number = DefaultDepth> = Exclude<DeepKey<T, Depth>, `${string}??` | '??'>;
+/**
+ * Loop-unrolled DeepKey: processes 2 nesting levels per recursion call.
+ *
+ * For each key K of T:
+ *   - Emit K (level 1 path)
+ *   - If T[K] is an object, inline level 2:
+ *     - For each key K2 of T[K]:
+ *       - Emit `${K}.${K2}` (level 2 path)
+ *       - If T[K][K2] is an object, recurse with `${K}.${K2}.${DeepKeyUnrolled}`
+ *
+ * Key insight: DeepKeyUnrolled<T, Depth> has NO prefix parameter,
+ * so identical sub-types at the same depth are cached by TypeScript.
+ * Template literal distribution (`${prefix}.${union}`) is handled natively
+ * by TypeScript without extra type instantiation overhead.
+ */
+type DeepKeyUnrolled<T, Depth extends number> = Depth extends 0 ? T extends Primitive | readonly any[] ? never : DepthLimitMarker : IsAny$1<T> extends true ? never : T extends Primitive ? never : T extends readonly any[] ? never : string extends keyof T ? HASH_KEY | (IsAny$1<T[string]> extends true ? `${HASH_KEY}.${DepthLimitMarker}` : NonNullable<T[string]> extends Primitive | readonly any[] ? never : RecordLevel2<NonNullable<T[string]>, HASH_KEY, Depth>) : {
+    [K in keyof T & (string | number)]: (K & string) | (IsAny$1<T[K]> extends true ? `${K & string}.${DepthLimitMarker}` : NonNullable<T[K]> extends Primitive | readonly any[] ? never : ConcreteLevel2<NonNullable<T[K]>, K & string, Depth>);
+}[keyof T & (string | number)];
+/**
+ * Level 2 expansion for concrete-key objects.
+ * Enumerates V's keys and uses inline template literal distribution for level 3+.
+ */
+type ConcreteLevel2<V, ParentKey extends string, Depth extends number> = IsAny$1<V> extends true ? `${ParentKey}.${DepthLimitMarker}` : V extends Primitive ? never : V extends readonly any[] ? never : string extends keyof V ? `${ParentKey}.${HASH_KEY}` | (IsAny$1<V[string]> extends true ? `${ParentKey}.${HASH_KEY}.${DepthLimitMarker}` : NonNullable<V[string]> extends Primitive | readonly any[] ? never : `${ParentKey}.${HASH_KEY}.${DeepKeyUnrolled<NonNullable<V[string]>, Prev2<Depth>> & string}`) : {
+    [K2 in keyof V & (string | number)]: `${ParentKey}.${K2 & string}` | (IsAny$1<V[K2]> extends true ? `${ParentKey}.${K2 & string}.${DepthLimitMarker}` : NonNullable<V[K2]> extends Primitive | readonly any[] ? never : `${ParentKey}.${K2 & string}.${DeepKeyUnrolled<NonNullable<V[K2]>, Prev2<Depth>> & string}`);
+}[keyof V & (string | number)];
+/**
+ * Level 2 expansion for Record-value objects.
+ * When level 1 was a Record, its value type V is expanded at level 2.
+ */
+type RecordLevel2<V, ParentKey extends string, Depth extends number> = IsAny$1<V> extends true ? `${ParentKey}.${DepthLimitMarker}` : V extends Primitive ? never : V extends readonly any[] ? never : string extends keyof V ? `${ParentKey}.${HASH_KEY}` | (IsAny$1<V[string]> extends true ? `${ParentKey}.${HASH_KEY}.${DepthLimitMarker}` : NonNullable<V[string]> extends Primitive | readonly any[] ? never : `${ParentKey}.${HASH_KEY}.${DeepKeyUnrolled<NonNullable<V[string]>, Prev2<Depth>> & string}`) : {
+    [K2 in keyof V & (string | number)]: `${ParentKey}.${K2 & string}` | (IsAny$1<V[K2]> extends true ? `${ParentKey}.${K2 & string}.${DepthLimitMarker}` : NonNullable<V[K2]> extends Primitive | readonly any[] ? never : `${ParentKey}.${K2 & string}.${DeepKeyUnrolled<NonNullable<V[K2]>, Prev2<Depth>> & string}`);
+}[keyof V & (string | number)];
+type Prev2<N extends number> = N extends 20 ? 18 : N extends 19 ? 17 : N extends 18 ? 16 : N extends 17 ? 15 : N extends 16 ? 14 : N extends 15 ? 13 : N extends 14 ? 12 : N extends 13 ? 11 : N extends 12 ? 10 : N extends 11 ? 9 : N extends 10 ? 8 : N extends 9 ? 7 : N extends 8 ? 6 : N extends 7 ? 5 : N extends 6 ? 4 : N extends 5 ? 3 : N extends 4 ? 2 : N extends 3 ? 1 : N extends 2 ? 0 : N extends 1 ? 0 : never;
+
+/**
+ * DeepKeyFiltered - Filters paths by their resolved value type
+ *
+ * Returns only paths from DeepKey<T> that resolve to a specific type U.
+ * Useful for type-safe filtering of state paths by their value types.
+ *
+ * @example
+ * ```typescript
+ * type Data = {
+ *   isActive: boolean
+ *   name: string
+ *   count: number
+ *   user: { isAdmin: boolean }
+ * }
+ *
+ * // Only boolean paths
+ * type BoolPaths = DeepKeyFiltered<Data, boolean>
+ * // Result: "isActive" | "user.isAdmin"
+ *
+ * // Only string paths
+ * type StrPaths = DeepKeyFiltered<Data, string>
+ * // Result: "name"
+ * ```
+ */
+
+/**
+ * Filters DeepKey<T> to only include paths that resolve to type U.
+ *
+ * Uses mapped type with conditional filtering - maps over all possible paths,
+ * keeps those matching the target type, and extracts the union.
+ *
+ * @example Custom depth — propagates to DeepKey
+ * ```typescript
+ * // Only number paths, limited to 10 levels deep
+ * type ShallowNumbers = DeepKeyFiltered<State, number, 10>
+ * ```
+ */
+type DeepKeyFiltered<T, U, Depth extends number = DefaultDepth> = {
+    [K in ResolvableDeepKey<T, Depth>]: NonNullable<DeepValue<T, K>> extends U ? K : never;
+}[ResolvableDeepKey<T, Depth>];
+
+/**
+ * DeepValue utility type
+ *
+ * Extracts the value type for a given dot-notation path string.
+ * Handles nested objects, arrays, and optional properties.
+ *
+ * @example
+ * ```typescript
+ * type User = {
+ *   address: {
+ *     street: string
+ *     city: string
+ *   }
+ * }
+ *
+ * // DeepValue<User, "address.street"> = string
+ * // DeepValue<User, "address"> = { street: string, city: string }
+ * ```
+ */
+
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type DeepValue<T, Path extends string> = IsAny<T> extends true ? never : T extends readonly any[] ? T[number] : Path extends `${infer First}.${infer Rest}` ? First extends keyof T ? DeepValue<NonNullable<T[First]>, Rest> : string extends keyof T ? First extends HASH_KEY ? DeepValue<T[string], Rest> : unknown : unknown : Path extends HASH_KEY ? string extends keyof T ? T[string] : unknown : Path extends keyof T ? T[Path] : unknown;
+
+/**
+ * Boolean logic DSL type definitions
+ *
+ * Type-safe conditional expression DSL used by concerns and side effects
+ * for reactive condition checking against state.
+ */
+
+/**
+ * Path-value pair distributed over all valid paths.
+ * Each path is paired with its resolved value type, ensuring type safety.
+ * The distribution happens inside the tuple, not at the union level —
+ * this keeps BoolLogic's top-level union flat so `in` narrowing works.
+ */
+type PathValuePair<STATE, Depth extends number> = DeepKey<STATE, Depth> extends infer P ? P extends string ? [P, DeepValue<STATE, P>] : never : never;
+/**
+ * Path-value array pair for IN operator.
+ * Same distribution as PathValuePair but with array values.
+ */
+type PathValueArrayPair<STATE, Depth extends number> = DeepKey<STATE, Depth> extends infer P ? P extends string ? [P, DeepValue<STATE, P>[]] : never : never;
+/**
+ * Array-elements pair for CONTAINS_ANY / CONTAINS_ALL operators.
+ * Same distribution as PathArrayElementPair but the second element is an array
+ * of items, enabling multi-value containment checks.
+ */
+type PathArrayElementsPair<STATE, Depth extends number> = DeepKey<STATE, Depth> extends infer P ? P extends string ? NonNullable<DeepValue<STATE, P>> extends readonly (infer Item)[] ? [P, Item[]] : never : never : never;
+/**
+ * Paths that resolve to number, plus `.length` on array-valued paths.
+ * Allows GT/LT/GTE/LTE to compare against array lengths without
+ * polluting DeepKey with virtual paths.
+ */
+type NumericPaths<STATE, Depth extends number> = DeepKeyFiltered<STATE, number, Depth> | `${DeepKeyFiltered<STATE, readonly unknown[], Depth>}.length`;
+/**
+ * Boolean logic DSL for conditional expressions
+ *
+ * Provides a declarative way to express conditions against state paths.
+ * Used by concerns (disabledWhen, visibleWhen) and side effects.
+ *
+ * Operators:
+ * - IS_EQUAL: Compare path value to expected value (value must match path type)
+ * - EXISTS: Check if path value is not null/undefined
+ * - IS_EMPTY: Check if path value is empty (string/array/object)
+ * - AND/OR/NOT: Boolean combinators
+ * - GT/LT/GTE/LTE: Numeric comparisons (only on number paths or array.length)
+ * - IN: Check if path value is in allowed list (values must match path type)
+ * - CONTAINS_ANY: Check if array at path contains any of the given elements
+ * - CONTAINS_ALL: Check if array at path contains all of the given elements
+ * - Shorthand: [path, value] tuple as shorthand for IS_EQUAL
+ *
+ * @example
+ * ```typescript
+ * // Simple equality check
+ * const isAdmin: BoolLogic<State> = { IS_EQUAL: ['user.role', 'admin'] }
+ *
+ * // Shorthand equality (equivalent to IS_EQUAL)
+ * const isAdmin2: BoolLogic<State> = ['user.role', 'admin']
+ *
+ * // Combined conditions with shorthand
+ * const canEdit: BoolLogic<State> = {
+ *   AND: [
+ *     ['user.role', 'editor'],
+ *     { EXISTS: 'document.id' },
+ *     { NOT: ['document.status', 'locked'] }
+ *   ]
+ * }
+ *
+ * // Numeric comparison
+ * const isExpensive: BoolLogic<State> = { GT: ['product.price', 100] }
+ *
+ * // Array length comparison
+ * const hasManyItems: BoolLogic<State> = { GT: ['cart.items.length', 5] }
+ * ```
+ */
+type BoolLogic<STATE, Depth extends number = DefaultDepth> = {
+    IS_EQUAL: PathValuePair<STATE, Depth>;
+} | {
+    EXISTS: DeepKey<STATE, Depth>;
+} | {
+    IS_EMPTY: DeepKey<STATE, Depth>;
+} | {
+    AND: BoolLogic<STATE, Depth>[];
+} | {
+    OR: BoolLogic<STATE, Depth>[];
+} | {
+    NOT: BoolLogic<STATE, Depth>;
+} | {
+    GT: [NumericPaths<STATE, Depth>, number];
+} | {
+    LT: [NumericPaths<STATE, Depth>, number];
+} | {
+    GTE: [NumericPaths<STATE, Depth>, number];
+} | {
+    LTE: [NumericPaths<STATE, Depth>, number];
+} | {
+    IN: PathValueArrayPair<STATE, Depth>;
+} | {
+    CONTAINS_ANY: PathArrayElementsPair<STATE, Depth>;
+} | {
+    CONTAINS_ALL: PathArrayElementsPair<STATE, Depth>;
+} | PathValuePair<STATE, Depth>;
+
+/**
+ * GenericMeta interface
+ *
+ * Base metadata type for change tracking with standard properties.
+ * Can be extended with custom properties for specific use cases.
+ *
+ * @example
+ * ```typescript
+ * interface CustomMeta extends GenericMeta {
+ *   timestamp: number
+ *   userId: string
+ * }
+ * ```
+ */
+interface GenericMeta {
+    /**
+     * Indicates if the change originated from a sync path side-effect.
+     * Used to track cascading changes triggered by synchronization logic.
+     */
+    isSyncPathChange?: boolean;
+    /**
+     * Indicates if the change originated from a flip path side-effect.
+     * Used to track bidirectional synchronization changes.
+     */
+    isFlipPathChange?: boolean;
+    /**
+     * Indicates if the change was triggered programmatically rather than by user action.
+     * Useful for distinguishing between automated and manual state updates.
+     */
+    isProgramaticChange?: boolean;
+    /**
+     * Indicates if the change originated from an aggregation side-effect.
+     * Used to track changes triggered by aggregation logic.
+     */
+    isAggregationChange?: boolean;
+    /**
+     * Indicates if the change originated from a listener side-effect.
+     * Used to track changes triggered by listener callbacks.
+     */
+    isListenerChange?: boolean;
+    /**
+     * Indicates if the change originated from a clear paths side-effect.
+     * Used to track changes triggered by clear paths logic (WASM-only).
+     */
+    isClearPathChange?: boolean;
+    /**
+     * Indicates if the change originated from a computation side-effect (SUM/AVG).
+     * Used to track changes triggered by computation logic.
+     */
+    isComputationChange?: boolean;
+    /**
+     * Identifies the originator of the change.
+     * Can be a user ID, component name, or any identifier string.
+     */
+    sender?: string;
+}
+
+/**
+ * ArrayOfChanges type
+ *
+ * Represents an array of changes with paths, values, and metadata.
+ * Each change is a tuple of [path, value, metadata].
+ *
+ * @example
+ * ```typescript
+ * type User = {
+ *   name: string
+ *   age: number
+ * }
+ *
+ * const changes: ArrayOfChanges<User, GenericMeta> = [
+ *   ["name", "John", { sender: "user-123" }],
+ *   ["age", 30, { isProgramaticChange: true }]
+ * ]
+ * ```
+ */
+
+/**
+ * Represents an array of change tuples.
+ * Each tuple contains:
+ * - path: A valid deep key path for the data structure
+ * - value: The value at that path (properly typed based on the path)
+ * - meta: Metadata about the change
+ */
+type ArrayOfChanges<DATA, META extends GenericMeta = GenericMeta> = {
+    [K in DeepKey<DATA>]: [K, DeepValue<DATA, K>, META] | [K, DeepValue<DATA, K>];
+}[DeepKey<DATA>][];
+
+/**
+ * Concern type utilities
+ *
+ * Generic type helpers for working with concern arrays and extracting
+ * their return types for proper type-safe concern registration and reading.
+ */
+
+/**
+ * Validation schema interface — the minimal contract for validation.
+ *
+ * Any library whose schema exposes `safeParse()` with this shape works
+ * out of the box (Zod, Valibot, ArkType, or a plain object).
+ */
+interface ValidationSchema<T = unknown> {
+    safeParse(data: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            errors: {
+                path: (string | number)[];
+                message: string;
+            }[];
+        };
+    };
+}
+/**
+ * Config type for the validationState concern at a specific path.
+ *
+ * Defined here (not in concerns/prebuilts/validation-state.ts) to avoid
+ * circular imports when used in ConcernRegistrationMap.
+ *
+ * Can be a schema for the path's own value type, or a scoped schema
+ * targeting a different path in the same state.
+ */
+type ValidationStateInput<DATA, PATH extends DeepKey<DATA, Depth>, Depth extends number = DefaultDepth> = {
+    schema: ValidationSchema<DeepValue<DATA, PATH>>;
+} | {
+    [SCOPE in ResolvableDeepKey<DATA, Depth>]: {
+        scope: SCOPE;
+        schema: ValidationSchema<DeepValue<DATA, SCOPE>>;
+    };
+}[ResolvableDeepKey<DATA, Depth>];
+/**
+ * Get the appropriate registration config type for a concern at a given path.
+ *
+ * - validationState: schema must match DeepValue<DATA, PATH> — path-dependent
+ * - BoolLogic-based concerns: boolLogic paths are typed against DATA
+ * - Template-based concerns: fixed { template: string }
+ * - Custom concerns: fall back to Record<string, unknown>
+ */
+type ConcernConfigFor<C, DATA extends object, PATH extends DeepKey<DATA, Depth>, Depth extends number = DefaultDepth> = C extends {
+    name: 'validationState';
+} ? ValidationStateInput<DATA, PATH, Depth> : C extends {
+    evaluate: (props: infer P) => any;
+} ? P extends {
+    boolLogic: any;
+} ? {
+    boolLogic: BoolLogic<DATA, Depth>;
+} : Omit<P, 'state' | 'path' | 'value'> : Record<string, unknown>;
+/**
+ * Extract the return type from a concern's evaluate function
+ *
+ * Used internally to determine what a concern evaluates to,
+ * enabling type-safe concern result objects.
+ *
+ * @example
+ * ```typescript
+ * type MyConcern = { evaluate: (...args: any[]) => boolean }
+ * type Result = ExtractEvaluateReturn<MyConcern>  // boolean
+ * ```
+ */
+type ExtractEvaluateReturn<T> = T extends {
+    evaluate: (...args: any[]) => infer R;
+} ? R : never;
+/**
+ * Dynamically build an evaluated concerns object from a CONCERNS array
+ *
+ * Maps each concern's name to its return type, creating a properly typed
+ * object that represents all concerns that can be registered/evaluated.
+ *
+ * @example
+ * ```typescript
+ * const concerns = [
+ *   { name: 'validationState', evaluate: () => ({ isError: boolean, errors: [] }) },
+ *   { name: 'tooltip', evaluate: () => string }
+ * ] as const
+ *
+ * type Evaluated = EvaluatedConcerns<typeof concerns>
+ * // { validationState?: { isError: boolean, errors: [] }, tooltip?: string }
+ * ```
+ */
+type EvaluatedConcerns<CONCERNS extends readonly any[]> = {
+    [K in CONCERNS[number] as K['name']]?: ExtractEvaluateReturn<K>;
+};
+/**
+ * Maps field paths to per-concern config objects.
+ *
+ * When CONCERNS is provided (e.g., from createGenericStore's CONCERNS generic),
+ * each concern config is type-checked against:
+ * - The concern's own EXTRA_PROPS (e.g., `{ boolLogic: ... }` for disabledWhen)
+ * - The path's value type for validationState (schema must match DeepValue<DATA, PATH>)
+ *
+ * Without CONCERNS (standalone usage), falls back to loose typing for backward compatibility.
+ *
+ * @example
+ * ```typescript
+ * // Works with any library implementing ValidationSchema (Zod, Valibot, ArkType, etc.)
+ * const registration: ConcernRegistrationMap<MyFormState> = {
+ *   email: { validationState: { schema: emailSchema } },
+ *   name: { validationState: { schema: nameSchema } },
+ * }
+ * ```
+ */
+type ConcernRegistrationMap<DATA extends object, CONCERNS extends readonly any[] = readonly any[], Depth extends number = DefaultDepth> = Partial<{
+    [PATH in DeepKey<DATA, Depth>]: Partial<{
+        [C in CONCERNS[number] as C extends {
+            name: string;
+        } ? C['name'] : never]: ConcernConfigFor<C, DATA, PATH, Depth>;
+    }>;
+}>;
+
+/**
+ * Lazy listener validators — O(N) base + O(K) per-listener validation
+ *
+ * These types power the `listeners()` helper function that scales to large state
+ * types without hitting TS2589.
+ *
+ * Unlike the direct `ListenerRegistration<DATA>[]` type which resolves
+ * `DeepKey<DATA>` for path/scope on every element, these validators only evaluate
+ * `DeepValue` for the K listeners you actually write.
+ *
+ * Valid listener combinations:
+ * 1. `{ path: string, fn }` — scope defaults to path → scoped state
+ * 2. `{ path: string, scope: null, fn }` — explicit null scope → full DATA
+ * 3. `{ path: string, scope: string, fn }` — scope must be prefix of path
+ * 4. `{ path: null, fn }` — watch everything, scope defaults to null → full DATA
+ * 5. `{ path: null, scope: null, fn }` — same as above, explicit
+ *
+ * **Inline fn restriction**: Fns with untyped (any) parameters are rejected.
+ * Use `OnStateListener<DATA, ScopedState>` to explicitly type your fn.
+ */
+
+/**
+ * True if Prefix is a dot-separated ancestor of Path (or equals Path).
+ *
+ * @example
+ * IsPrefixOf<'user', 'user'>          → true   (equal)
+ * IsPrefixOf<'user', 'user.name'>     → true   (parent)
+ * IsPrefixOf<'user', 'username'>      → false  (different segment)
+ * IsPrefixOf<'cart', 'user.name'>     → false  (unrelated)
+ */
+type IsPrefixOf<Prefix extends string, Path extends string> = Path extends Prefix ? true : Path extends `${Prefix}.${string}` ? true : false;
+/**
+ * Derive the sub-state type from scope.
+ * - null scope → full DATA
+ * - string scope → DeepValue<DATA, Scope>
+ *
+ * Uses `Scope & string` to satisfy DeepValue's string constraint
+ * when Scope is inferred from a mapped type.
+ */
+type ScopedState<DATA extends object, Scope> = Scope extends null ? DATA : Scope extends string ? DeepValue<DATA, Scope & string> : DATA;
+/**
+ * Extract the effective scope from a listener element.
+ *
+ * When 'scope' key exists with a non-undefined value, returns that value.
+ * When 'scope' key is missing or undefined, returns the path as default.
+ */
+type EffectiveScope<T, P> = 'scope' extends keyof T ? Exclude<T[keyof T & 'scope'], undefined> extends never ? P : Exclude<T[keyof T & 'scope'], undefined> : P;
+/**
+ * Detect if a function's first parameter is `any`.
+ * Uses the `0 extends 1 & T` trick: only true when T is `any`.
+ *
+ * When true, the fn has untyped parameters (e.g., `(_changes, _state) => ...`
+ * without explicit typing). We reject these to force users to use
+ * `OnStateListener<DATA, ScopedState>` for type safety.
+ */
+type HasAnyFirstParam<F> = F extends (...args: infer A) => any ? A extends [infer P1, ...any[]] ? 0 extends 1 & P1 ? true : false : false : false;
+/**
+ * Error marker type for untyped listener fns.
+ * Produces a clear error message when the user passes an untyped inline fn.
+ */
+type TypedFnRequired<DATA extends object, SUB_STATE, META extends GenericMeta> = OnStateListener<DATA, SUB_STATE, META> & {
+    __error: 'Listener fn must be explicitly typed. Use OnStateListener<DATA, ScopedState> or type the parameters directly.';
+};
+/**
+ * Returns the fn type for a listener element, rejecting untyped fns.
+ *
+ * When the user's fn has `any` params (implicit from inference), returns
+ * a branded error type that produces a clear type error.
+ * When the fn is explicitly typed (standalone or annotated), returns the
+ * expected OnStateListener type for assignability checking.
+ */
+type ValidatedFn<DATA extends object, META extends GenericMeta, SUB_STATE, F> = HasAnyFirstParam<F> extends true ? TypedFnRequired<DATA, SUB_STATE, META> : OnStateListener<DATA, SUB_STATE, META>;
+/**
+ * Validates a single listener element.
+ *
+ * When scope is omitted (undefined), it defaults to path:
+ * - path is string → fn gets DeepValue<DATA, path>
+ * - path is null → fn gets full DATA
+ *
+ * When scope is explicitly provided:
+ * - scope: null → fn gets full DATA
+ * - scope: string → must be prefix of path, fn gets DeepValue<DATA, scope>
+ *
+ * Rejects fns with untyped (any) parameters — forces explicit typing via
+ * OnStateListener<DATA, ScopedState>.
+ */
+type CheckListenerElement<DATA extends object, META extends GenericMeta, T> = T extends {
+    path: infer P;
+    fn: infer F;
+} ? EffectiveScope<T, P> extends infer ES ? [
+    P,
+    ES
+] extends [string, string] ? IsPrefixOf<ES & string, P & string> extends true ? 'scope' extends keyof T ? {
+    path: P;
+    scope: ES;
+    fn: ValidatedFn<DATA, META, ScopedState<DATA, ES>, F>;
+} : {
+    path: P;
+    scope?: undefined;
+    fn: ValidatedFn<DATA, META, ScopedState<DATA, ES>, F>;
+} : {
+    path: P;
+    scope: never;
+    fn: OnStateListener<DATA, never, META>;
+} : [
+    P,
+    ES
+] extends [string, null] ? {
+    path: P;
+    scope: null;
+    fn: ValidatedFn<DATA, META, DATA, F>;
+} : [
+    P,
+    ES
+] extends [null, null] ? 'scope' extends keyof T ? {
+    path: null;
+    scope: null;
+    fn: ValidatedFn<DATA, META, DATA, F>;
+} : {
+    path: null;
+    scope?: undefined;
+    fn: ValidatedFn<DATA, META, DATA, F>;
+} : T : T : T;
+/**
+ * Validates an array of listener objects lazily — O(K) where K = listeners written.
+ *
+ * Per element:
+ * 1. path must be ResolvableDeepKey<DATA> | null (enforced by function constraint)
+ * 2. scope is optional — defaults to path when omitted
+ * 3. When both non-null: scope must be prefix of path
+ * 4. fn must be explicitly typed (rejects untyped `any` params)
+ * 5. fn receives correctly-typed scoped state
+ */
+type CheckListeners<DATA extends object, META extends GenericMeta, T extends readonly {
+    path: string | null;
+    scope?: string | null | undefined;
+    fn: (...args: any[]) => any;
+}[], _Depth extends number = DefaultDepth> = {
+    [I in keyof T]: CheckListenerElement<DATA, META, T[I]>;
+};
+
+/**
+ * Direct pair types — O(N²) path unions for side effects
+ *
+ * These types enumerate all valid path combinations eagerly.
+ * Simple to use as type annotations but hit TS2589 at ~1,500 paths.
+ *
+ * For large state types, use the curried helper functions (syncPairs, flipPairs, etc.)
+ * which use lazy validators from `pair-validators.ts` instead.
+ *
+ * @example
+ * ```typescript
+ * type State = {
+ *   user: { email: string }
+ *   profile: { email: string }
+ *   count: number
+ * }
+ *
+ * // ✓ Valid: both paths are string
+ * const sync: SyncPair<State> = ['user.email', 'profile.email']
+ *
+ * // ✗ Error: 'user.email' (string) can't sync with 'count' (number)
+ * const invalid: SyncPair<State> = ['user.email', 'count']
+ * ```
+ */
+
+/**
+ * Get all paths in DATA that have the same value type as the value at PATH
+ */
+type PathsWithSameValueAs<DATA extends object, PATH extends ResolvableDeepKey<DATA, Depth>, Depth extends number = DefaultDepth> = {
+    [K in ResolvableDeepKey<DATA, Depth>]: NonNullable<DeepValue<DATA, K>> extends NonNullable<DeepValue<DATA, PATH>> ? NonNullable<DeepValue<DATA, PATH>> extends NonNullable<DeepValue<DATA, K>> ? K : never : never;
+}[ResolvableDeepKey<DATA, Depth>];
+/**
+ * A tuple of two paths that must have the same value type.
+ * Format: [path1, path2]
+ *
+ * **Scaling note**: This type is O(N²) where N = number of paths. It hits TS2589
+ * at ~1,500 paths. For large state types, use the `syncPairs()` helper function
+ * or `store.syncPairs()` (pre-warmed from `createGenericStore`) instead —
+ * they scale to ~50K–80K paths.
+ *
+ * @example
+ * const pair: SyncPair<State> = ['user.email', 'profile.email']
+ *
+ * @example Custom depth — propagates to DeepKey and PathsWithSameValueAs
+ * ```typescript
+ * // Limit path traversal to 10 levels
+ * const shallow: SyncPair<State, 10> = ['user.email', 'profile.email']
+ * ```
+ */
+type SyncPair<DATA extends object, Depth extends number = DefaultDepth> = {
+    [P1 in ResolvableDeepKey<DATA, Depth>]: [
+        P1,
+        PathsWithSameValueAs<DATA, P1, Depth>
+    ];
+}[ResolvableDeepKey<DATA, Depth>];
+/**
+ * A tuple of two paths for flip (alias for SyncPair).
+ * Format: [path1, path2]
+ *
+ * **Scaling note**: O(N²) — hits TS2589 at ~1,500 paths. Use `flipPairs()` helper
+ * or `store.flipPairs()` for large state types.
+ *
+ * @example
+ * const pair: FlipPair<State> = ['isActive', 'isInactive']
+ */
+type FlipPair<DATA extends object, Depth extends number = DefaultDepth> = SyncPair<DATA, Depth>;
+/**
+ * A tuple for aggregation: [target, source] or [target, source, excludeWhen]
+ * First element (left) is ALWAYS the target (aggregated) path.
+ * Second element is a source path.
+ * Optional third element is a BoolLogic condition — when true, this source is excluded.
+ *
+ * Multiple pairs can point to same target for multi-source aggregation.
+ *
+ * **Scaling note**: O(N²) — hits TS2589 at ~1,500 paths. Use `aggregationPairs()` helper
+ * or `store.aggregationPairs()` for large state types.
+ *
+ * @example
+ * // target <- source (target is always first/left)
+ * const aggs: AggregationPair<State>[] = [
+ *   ['total', 'price1'],
+ *   ['total', 'price2', { IS_EQUAL: ['price2.disabled', true] }],
+ * ]
+ */
+type AggregationPair<DATA extends object, Depth extends number = DefaultDepth> = {
+    [P1 in ResolvableDeepKey<DATA, Depth>]: [P1, PathsWithSameValueAs<DATA, P1, Depth>] | [P1, PathsWithSameValueAs<DATA, P1, Depth>, BoolLogic<DATA, Depth>];
+}[ResolvableDeepKey<DATA, Depth>];
+/**
+ * Supported computation operations for numeric reduction.
+ */
+type ComputationOp = 'SUM' | 'AVG';
+/**
+ * A tuple for computation: [operation, target, source] or [operation, target, source, excludeWhen]
+ * First element is the operation (SUM, AVG).
+ * Second element is the target path (must be a number path).
+ * Third element is a source path (must be a number path).
+ * Optional fourth element is a BoolLogic condition — when true, this source is excluded.
+ *
+ * Multiple pairs can point to same target for multi-source computation.
+ *
+ * **Scaling note**: O(N²) — hits TS2589 at ~1,500 paths. Use `computationPairs()` helper
+ * or `store.computationPairs()` for large state types.
+ *
+ * @example
+ * const comps: ComputationPair<State>[] = [
+ *   ['SUM', 'total', 'price1'],
+ *   ['SUM', 'total', 'price2', { IS_EQUAL: ['price2.disabled', true] }],
+ *   ['AVG', 'average', 'score1'],
+ *   ['AVG', 'average', 'score2'],
+ * ]
+ */
+type ComputationPair<DATA extends object, Depth extends number = DefaultDepth> = {
+    [TARGET in DeepKeyFiltered<DATA, number, Depth>]: [ComputationOp, TARGET, DeepKeyFiltered<DATA, number, Depth>] | [
+        ComputationOp,
+        TARGET,
+        DeepKeyFiltered<DATA, number, Depth>,
+        BoolLogic<DATA, Depth>
+    ];
+}[DeepKeyFiltered<DATA, number, Depth>];
+
+/**
+ * Lazy pair validators — O(N) base + O(K) per-pair DeepValue check
+ *
+ * These types power the helper functions (syncPairs, flipPairs, etc.)
+ * that scale to large state types without hitting TS2589.
+ *
+ * Unlike the direct pair types (SyncPair, FlipPair, etc.) which are O(N²),
+ * these validators only evaluate DeepValue for the K pairs you actually write.
+ */
+
+/**
+ * Validates that two paths resolve to the same value type.
+ * Only evaluates DeepValue when P1, P2 are concrete literals — O(1) per pair.
+ * Wraps in [T] extends [U] to prevent distributive conditional.
+ *
+ * Returns [P1, P2] on match, [P1, never] on mismatch.
+ */
+type CheckPairValueMatch<DATA extends object, P1 extends string, P2 extends string, Depth extends number = DefaultDepth> = [P1] extends [ResolvableDeepKey<DATA, Depth>] ? [P2] extends [ResolvableDeepKey<DATA, Depth>] ? [NonNullable<DeepValue<DATA, P1>>] extends [
+    NonNullable<DeepValue<DATA, P2>>
+] ? [NonNullable<DeepValue<DATA, P2>>] extends [
+    NonNullable<DeepValue<DATA, P1>>
+] ? [P1, P2] : [P1, never] : [P1, never] : never : never;
+/**
+ * Validates an array of [P1, P2] sync/flip pairs lazily — O(K) where K = pairs written.
+ */
+type CheckSyncPairs<DATA extends object, T extends readonly [string, string][], Depth extends number = DefaultDepth> = {
+    [I in keyof T]: T[I] extends [
+        infer P1 extends string,
+        infer P2 extends string
+    ] ? CheckPairValueMatch<DATA, P1, P2, Depth> : T[I];
+};
+/**
+ * Validates that two paths both resolve to number.
+ * Returns [ComputationOp, P1, P2] or [ComputationOp, P1, P2, BoolLogic] on match.
+ */
+type CheckComputationPairValueMatch<DATA extends object, P1 extends string, P2 extends string, Depth extends number = DefaultDepth> = [P1] extends [DeepKeyFiltered<DATA, number, Depth>] ? [P2] extends [DeepKeyFiltered<DATA, number, Depth>] ? true : false : false;
+/**
+ * Validates an array of aggregation pairs: [target, source] or [target, source, BoolLogic].
+ * Each pair checks that target and source resolve to the same value type.
+ */
+type CheckAggregationPairs<DATA extends object, T extends readonly (readonly [string, string] | readonly [string, string, BoolLogic<DATA, Depth>])[], Depth extends number = DefaultDepth> = {
+    [I in keyof T]: T[I] extends readonly [
+        infer P1 extends string,
+        infer P2 extends string,
+        infer BL
+    ] ? CheckPairValueMatch<DATA, P1, P2, Depth> extends [P1, P2] ? [P1, P2, BL] : [P1, never, BL] : T[I] extends readonly [infer P1 extends string, infer P2 extends string] ? CheckPairValueMatch<DATA, P1, P2, Depth> : T[I];
+};
+/**
+ * Validates an array of computation pairs: [op, target, source] or [op, target, source, BoolLogic].
+ * Both target and source must be number paths.
+ */
+type CheckComputationPairs<DATA extends object, T extends readonly (readonly [ComputationOp, string, string] | readonly [ComputationOp, string, string, BoolLogic<DATA, Depth>])[], Depth extends number = DefaultDepth> = {
+    [I in keyof T]: T[I] extends readonly [
+        infer Op extends ComputationOp,
+        infer P1 extends string,
+        infer P2 extends string,
+        infer BL
+    ] ? CheckComputationPairValueMatch<DATA, P1, P2, Depth> extends true ? [Op, P1, P2, BL] : [Op, P1, never, BL] : T[I] extends readonly [
+        infer Op extends ComputationOp,
+        infer P1 extends string,
+        infer P2 extends string
+    ] ? CheckComputationPairValueMatch<DATA, P1, P2, Depth> extends true ? [Op, P1, P2] : [Op, P1, never] : T[I];
+};
+
+/** Recursively makes all properties required, stripping undefined */
+type DeepRequired<T> = {
+    [K in keyof T]-?: NonNullable<T[K]> extends object ? DeepRequired<NonNullable<T[K]>> : NonNullable<T[K]>;
+};
+/**
+ * Recursively makes all properties optional (allows undefined values).
+ *
+ * Written as a conditional type so TypeScript distributes it over union members
+ * automatically — null/undefined fall through to `: T` and are preserved as-is.
+ * Array check comes before object so arrays are not mapped over their keys.
+ */
+type DeepPartial<T> = T extends (infer U)[] ? DeepPartial<U>[] : T extends readonly (infer U)[] ? readonly DeepPartial<U>[] : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+
+/**
+ * Validated pair branded types
+ *
+ * Phantom types for pre-validated pair arrays returned by helper functions
+ * (syncPairs, flipPairs, aggregationPairs, computationPairs).
+ *
+ * Brands serve two purposes:
+ * 1. SideEffects accepts them without re-resolving the O(N²) direct pair types
+ * 2. DATA generic prevents cross-store use (pairs from StoreA can't go to StoreB)
+ *
+ * Zero runtime cost — brands are erased at compile time.
+ */
+
+declare const VALIDATED: unique symbol;
+declare const STORE_DATA: unique symbol;
+/** Pre-validated sync pair array. Returned by `syncPairs()`. Branded with DATA to prevent cross-store use. */
+type ValidatedSyncPairs<DATA extends object = object> = [
+    string,
+    string
+][] & {
+    [VALIDATED]: 'sync';
+    [STORE_DATA]: DATA;
+};
+/** Pre-validated flip pair array. Returned by `flipPairs()`. Branded with DATA to prevent cross-store use. */
+type ValidatedFlipPairs<DATA extends object = object> = [
+    string,
+    string
+][] & {
+    [VALIDATED]: 'flip';
+    [STORE_DATA]: DATA;
+};
+/** Pre-validated aggregation pair array. Returned by `aggregationPairs()`. Branded with DATA to prevent cross-store use. */
+type ValidatedAggregationPairs<DATA extends object = object> = ([string, string] | [string, string, unknown])[] & {
+    [VALIDATED]: 'aggregation';
+    [STORE_DATA]: DATA;
+};
+/** Pre-validated computation pair array. Returned by `computationPairs()`. Branded with DATA to prevent cross-store use. */
+type ValidatedComputationPairs<DATA extends object = object> = ([ComputationOp, string, string] | [ComputationOp, string, string, unknown])[] & {
+    [VALIDATED]: 'computation';
+    [STORE_DATA]: DATA;
+};
+/** Pre-validated listener array. Returned by `listeners()`. Branded with DATA to prevent cross-store use.
+ * Uses intersection with ListenerRegistration[] so it's assignable to the listeners field
+ * without needing a union — preserving contextual typing for inline fn parameters.
+ */
+type ValidatedListeners<DATA extends object = object, META extends GenericMeta = GenericMeta> = ListenerRegistration<DATA, META>[] & {
+    [VALIDATED]: 'listeners';
+    [STORE_DATA]: DATA;
+};
+
+interface BaseConcernProps<STATE, PATH extends string> {
+    state: STATE;
+    path: PATH;
+    value: unknown;
+}
+interface ConcernType<NAME extends string = string, EXTRA_PROPS = Record<string, unknown>, RETURN_TYPE = unknown> {
+    name: NAME;
+    description: string;
+    /** Evaluated inside effect() - all state accesses are tracked */
+    evaluate: (props: BaseConcernProps<Record<string, unknown>, string> & EXTRA_PROPS) => RETURN_TYPE;
+}
+interface ConcernRegistration {
+    id: string;
+    path: string;
+    concernName: string;
+    concern: ConcernType;
+    config: Record<string, unknown>;
+    dispose: () => void;
+}
+
+/**
+ * Debug Timing Utilities
+ *
+ * Provides timing measurement for concerns and listeners
+ * to detect slow operations during development.
+ */
+type TimingType = 'concerns' | 'listeners' | 'registration';
+interface TimingMeta {
+    path: string;
+    name: string;
+}
+interface Timing {
+    run: <T>(type: TimingType, fn: () => T, meta: TimingMeta) => T;
+    reportBatch: (type: TimingType) => void;
+}
+
+/**
+ * WASM Bridge — Thin namespace over Rust/WASM exports.
+ *
+ * Uses serde-wasm-bindgen for hot-path functions (processChanges,
+ * shadowInit) — JS objects cross the boundary directly without JSON
+ * string intermediary. Registration functions still use JSON strings
+ * (cold path, simpler).
+ *
+ * Loading is handled by `wasm/lifecycle.ts`. After loading, all bridge
+ * functions are synchronous.
+ *
+ * @module wasm/bridge
+ */
+
+/** A single state change (input or output). */
+interface Change {
+    path: string;
+    value: unknown;
+    origin?: string;
+}
+/** A single dispatch entry with sequential ID and input change references. */
+interface DispatchEntry {
+    dispatch_id: number;
+    subscriber_id: number;
+    scope_path: string;
+    /** Indexes into ProcessResult.changes array. */
+    input_change_ids: number[];
+}
+/** A group of dispatches to execute sequentially. */
+interface DispatchGroup {
+    dispatches: DispatchEntry[];
+}
+/** A target for propagating produced changes from child to parent dispatch. */
+interface PropagationTarget {
+    target_dispatch_id: number;
+    /** Prefix to prepend to child's relative paths for the target's scope. */
+    remap_prefix: string;
+}
+/** Pre-computed execution plan with propagation map. */
+interface FullExecutionPlan {
+    groups: DispatchGroup[];
+    /** propagation_map[dispatch_id] = targets to forward produced changes to. */
+    propagation_map: PropagationTarget[][];
+}
+/** Validator dispatch info for JS-side execution. */
+interface ValidatorDispatch {
+    validator_id: number;
+    output_path: string;
+    dependency_values: Record<string, string>;
+}
+/**
+ * Extends a base tuple with an optional trailing BoolLogic condition (JSON-serialized).
+ * Used by aggregation and computation pairs to share the "optional excludeWhen" pattern.
+ */
+type WasmPairWithCondition<Base extends [...string[]]> = [...Base] | [...Base, condition: string];
+/** WASM-side aggregation pair: [target, source] with optional excludeWhen condition. */
+type WasmAggregationPair = WasmPairWithCondition<[
+    target: string,
+    source: string
+]>;
+/** WASM-side computation pair: [operation, target, source] with optional excludeWhen condition. */
+type WasmComputationPair = WasmPairWithCondition<[
+    op: string,
+    target: string,
+    source: string
+]>;
+/** WASM-side sync pair: [source, target] — bidirectional sync. */
+type WasmSyncPair = [source: string, target: string];
+/** WASM-side flip pair: [source, target] — inverted boolean sync. */
+type WasmFlipPair = [source: string, target: string];
+/** WASM-side clear path rule: trigger paths → target paths to null. */
+interface WasmClearPathRule {
+    triggers: string[];
+    targets: string[];
+}
+/** WASM-side listener entry for topic-based dispatch. */
+interface WasmListenerEntry {
+    subscriber_id: number;
+    topic_path: string;
+    scope_path: string;
+}
+/** Consolidated registration input for side effects (sync, flip, aggregation, computation, clear, listeners). */
+interface SideEffectsRegistration {
+    registration_id: string;
+    sync_pairs?: WasmSyncPair[];
+    flip_pairs?: WasmFlipPair[];
+    aggregation_pairs?: WasmAggregationPair[];
+    computation_pairs?: WasmComputationPair[];
+    clear_paths?: WasmClearPathRule[];
+    listeners?: WasmListenerEntry[];
+}
+/** Consolidated registration output from side effects registration. */
+interface SideEffectsResult {
+    sync_changes: Change[];
+    aggregation_changes: Change[];
+    computation_changes: Change[];
+    registered_listener_ids: number[];
+}
+/** WASM-side BoolLogic entry for declarative boolean evaluation. */
+interface WasmBoolLogicEntry {
+    output_path: string;
+    tree_json: string;
+}
+/** WASM-side validator entry for validation orchestration. */
+interface WasmValidatorEntry {
+    validator_id: number;
+    output_path: string;
+    dependency_paths: string[];
+    scope: string;
+}
+/** WASM-side ValueLogic entry for declarative value computation. */
+interface WasmValueLogicEntry {
+    output_path: string;
+    tree_json: string;
+}
+/** Consolidated registration input for concerns (BoolLogic, validators, and ValueLogic). */
+interface ConcernsRegistration {
+    registration_id: string;
+    bool_logics?: WasmBoolLogicEntry[];
+    validators?: WasmValidatorEntry[];
+    value_logics?: WasmValueLogicEntry[];
+}
+/** Consolidated registration output from concerns registration. */
+interface ConcernsResult {
+    bool_logic_changes: Change[];
+    registered_logic_ids: number[];
+    registered_validator_ids: number[];
+    value_logic_changes: Change[];
+    registered_value_logic_ids: number[];
+}
+/** Result of processChanges (Phase 1). */
+interface ProcessChangesResult {
+    state_changes: Change[];
+    changes: Change[];
+    validators_to_run: ValidatorDispatch[];
+    execution_plan: FullExecutionPlan | null;
+    has_work: boolean;
+}
+/**
+ * An isolated WASM pipeline instance.
+ * Each store gets its own pipeline so multiple Providers don't interfere.
+ * All methods are pre-bound to the pipeline's ID — consumers never pass IDs.
+ */
+interface WasmPipeline {
+    readonly id: number;
+    shadowInit: (state: object) => void;
+    shadowDump: () => unknown;
+    processChanges: (changes: Change[]) => ProcessChangesResult;
+    pipelineFinalize: (jsChanges: Change[]) => {
+        state_changes: Change[];
+    };
+    registerSideEffects: (reg: SideEffectsRegistration) => SideEffectsResult;
+    unregisterSideEffects: (registrationId: string) => void;
+    registerConcerns: (reg: ConcernsRegistration) => ConcernsResult;
+    unregisterConcerns: (registrationId: string) => void;
+    registerBoolLogic: (outputPath: string, tree: unknown) => number;
+    unregisterBoolLogic: (logicId: number) => void;
+    pipelineReset: () => void;
+    destroy: () => void;
+    /** Per-instance storage for validation schemas (can't cross WASM boundary). */
+    validatorSchemas: Map<number, ValidationSchema>;
+}
+
+/**
+ * PathGroups Data Structure
+ *
+ * A custom data structure that provides O(1) connected component lookups
+ * instead of O(V+E) recomputation on every change like graphology's connectedComponents.
+ *
+ * When wasmGraphType is set ('sync' | 'flip'), addEdge/removeEdge automatically
+ * mirror registrations to WASM bridge for pipeline processing.
+ *
+ * Operations complexity:
+ * - getAllGroups(): O(G) where G is number of groups (typically small)
+ * - getGroupPaths(path): O(1) lookup
+ * - addEdge(p1, p2): O(n) where n is smaller group size (merge)
+ * - removeEdge(p1, p2): O(n) for affected component
+ * - hasPath(path): O(1)
+ * - hasEdge(p1, p2): O(1)
+ */
+/** Graph type for WASM mirroring. When set, addEdge/removeEdge mirror to WASM. */
+type WasmGraphType = 'sync' | 'flip';
+/**
+ * PathGroups maintains connected components with O(1) lookups.
+ *
+ * Internal structure:
+ * - pathToGroup: Maps each path to its group ID
+ * - groupToPaths: Maps each group ID to the set of paths in that group
+ * - edges: Set of edge keys for edge existence checks and proper removal
+ * - adjacency: Maps each path to its direct neighbors (for split detection on removal)
+ * - nextGroupId: Counter for generating unique group IDs
+ */
+interface PathGroups {
+    pathToGroup: Map<string, number>;
+    groupToPaths: Map<number, Set<string>>;
+    edges: Set<string>;
+    adjacency: Map<string, Set<string>>;
+    nextGroupId: number;
+    wasmGraphType?: WasmGraphType;
+}
+
+/**
+ * Graph Type Definitions
+ *
+ * Type aliases for the PathGroups data structure used in sync and flip operations.
+ * These aliases maintain backward compatibility with the previous graphology-based API.
+ */
+
+/**
+ * Sync graph: Paths that must have synchronized values
+ * Type alias for PathGroups - maintains backward compatibility
+ */
+type SyncGraph = PathGroups;
+/**
+ * Flip graph: Paths with inverted boolean values
+ * Type alias for PathGroups - maintains backward compatibility
+ */
+type FlipGraph = PathGroups;
+
+/**
+ * Core Store Types
+ *
+ * Foundational type definitions for the store instance.
+ * These types are used throughout the library.
+ */
+
+/**
+ * Debug configuration for development tooling
+ */
+interface DebugConfig {
+    /** Enable timing measurement for concerns and listeners */
+    timing?: boolean;
+    /** Threshold in milliseconds for slow operation warnings (default: 5ms) */
+    timingThreshold?: number;
+    /** Enable tracking of processChanges calls and applied changes for testing/debugging */
+    track?: boolean;
+}
+/**
+ * A single recorded processChanges invocation
+ */
+interface DebugTrackEntry {
+    /** Input changes passed to processChanges as [path, value, meta] tuples */
+    input: [string, unknown, unknown][];
+    /** Changes actually applied to state proxy */
+    applied: {
+        path: string;
+        value: unknown;
+    }[];
+    /** Changes applied to _concerns proxy */
+    appliedConcerns: {
+        path: string;
+        value: unknown;
+    }[];
+    /** Timestamp of the call */
+    timestamp: number;
+}
+/**
+ * Debug tracking data exposed on StoreInstance when debug.track is enabled.
+ * Provides an append-only log of all processChanges calls and their effects.
+ */
+interface DebugTrack {
+    /** All recorded processChanges calls (append-only) */
+    calls: DebugTrackEntry[];
+    /** Reset all tracking data */
+    clear: () => void;
+}
+interface StoreConfig {
+    /** Error storage path (default: "_errors") */
+    errorStorePath?: string;
+    /** Max iterations for change processing (default: 100) */
+    maxIterations?: number;
+    /** Debug configuration for development tooling */
+    debug?: DebugConfig;
+    /** Use legacy TypeScript implementation instead of WASM (default: false) */
+    useLegacyImplementation?: boolean;
+}
+interface ProviderProps<DATA extends object> {
+    initialState: DATA;
+    children: ReactNode;
+}
+interface Aggregation {
+    id?: string;
+    targetPath: string;
+    sourcePaths: string[];
+}
+/** Reacts to scoped changes - receives relative paths and scoped state. Only fires for NESTED paths, not the path itself.
+ * Both input changes and return changes use paths relative to scope (or full paths when scope is null).
+ *
+ * When SUB_STATE is `any` (as in ListenerRegistration's default), the return type falls back to
+ * ArrayOfChanges<DATA> to avoid DeepKey<any> resolving to never.
+ */
+type IsAnyState<T> = 0 extends 1 & T ? true : false;
+type OnStateListener<DATA extends object = object, SUB_STATE = DATA, META extends GenericMeta = GenericMeta> = (changes: ArrayOfChanges<SUB_STATE, META>, state: SUB_STATE) => IsAnyState<SUB_STATE> extends true ? ArrayOfChanges<DATA, META> | undefined : ArrayOfChanges<SUB_STATE, META> | undefined;
+/**
+ * Listener registration with path (what to watch) and scope (how to present data)
+ *
+ * @example
+ * ```typescript
+ * // Watch user.profile.name, get full state
+ * {
+ *   path: 'user.profile.name',
+ *   scope: null,
+ *   fn: (changes, state) => {
+ *     // changes: [['user.profile.name', 'Alice', {}]] - FULL path
+ *     // state: full DATA object
+ *   }
+ * }
+ *
+ * // Watch user.profile.*, get scoped state
+ * {
+ *   path: 'user.profile',
+ *   scope: 'user.profile',
+ *   fn: (changes, state) => {
+ *     // changes: [['name', 'Alice', {}]] - RELATIVE to scope
+ *     // state: user.profile object
+ *   }
+ * }
+ *
+ * // Watch deep path, get parent scope
+ * {
+ *   path: 'p.123.g.abc.data.strike',
+ *   scope: 'p.123.g.abc',
+ *   fn: (changes, state) => {
+ *     // changes: [['data.strike', value, {}]] - relative to scope
+ *     // state: p.123.g.abc object
+ *   }
+ * }
+ * ```
+ */
+interface ListenerRegistration<DATA extends object = object, META extends GenericMeta = GenericMeta, Depth extends number = DefaultDepth> {
+    /**
+     * Path to watch - only changes under this path will trigger the listener
+     * null = watch all top-level paths
+     */
+    path: DeepKey<DATA, Depth> | null;
+    /**
+     * Scope for state and changes presentation
+     * - If omitted/undefined: defaults to `path` (scoped state matching the watched path)
+     * - If null: state is full DATA, changes use FULL paths
+     * - If set: state is value at scope, changes use paths RELATIVE to scope
+     *
+     * Note: Changes are filtered based on `path`, even when scope is null
+     */
+    scope?: DeepKey<DATA, Depth> | null;
+    fn: OnStateListener<DATA, any, META>;
+}
+interface ListenerHandlerRef {
+    scope: string | null;
+    fn: (...args: unknown[]) => unknown;
+}
+interface SideEffectGraphs<DATA extends object = object, META extends GenericMeta = GenericMeta> {
+    sync: SyncGraph;
+    flip: FlipGraph;
+    listeners: Map<string, ListenerRegistration<DATA, META>[]>;
+    sortedListenerPaths: string[];
+    /** O(1) lookup: subscriber_id -> handler ref. Populated by registerListener. */
+    listenerHandlers: Map<number, ListenerHandlerRef>;
+}
+interface Registrations {
+    concerns: Map<string, ConcernType[]>;
+    effectCleanups: Set<() => void>;
+    sideEffectCleanups: Map<string, () => void>;
+    aggregations: Map<string, Aggregation[]>;
+}
+interface ProcessingState<DATA extends object = object, META extends GenericMeta = GenericMeta> {
+    queue: ArrayOfChanges<DATA, META>;
+}
+/** Internal store state (NOT tracked - wrapped in ref()) */
+interface InternalState<DATA extends object = object, META extends GenericMeta = GenericMeta> {
+    graphs: SideEffectGraphs<DATA, META>;
+    registrations: Registrations;
+    processing: ProcessingState<DATA, META>;
+    timing: Timing;
+    config: DeepRequired<StoreConfig>;
+    /** Per-store WASM pipeline instance (null when using legacy implementation). */
+    pipeline: WasmPipeline | null;
+    /** Pending deferred destroy timer — cancelled on StrictMode re-mount. */
+    _destroyTimer?: ReturnType<typeof setTimeout> | undefined;
+}
+type ConcernValues = Record<string, Record<string, unknown>>;
+/** Two-proxy pattern: state and _concerns are independent to prevent infinite loops */
+interface StoreInstance<DATA extends object, META extends GenericMeta = GenericMeta> {
+    state: DATA;
+    _concerns: ConcernValues;
+    _internal: InternalState<DATA, META>;
+    /** Debug tracking data, only populated when debug.track is enabled */
+    _debug: DebugTrack | null;
+}
+
+interface ValidationError {
+    field?: string;
+    message: string;
+}
+interface ValidationStateResult {
+    isError: boolean;
+    errors: ValidationError[];
+}
+interface ValidationStateConcern {
+    name: 'validationState';
+    description: string;
+    evaluate: <SUB_STATE, PATH extends DeepKey<SUB_STATE>>(props: BaseConcernProps<SUB_STATE, PATH> & ValidationStateInput<SUB_STATE, PATH>) => ValidationStateResult;
+}
+declare const validationState: ValidationStateConcern;
+
+declare const disabledWhen: ConcernType<'disabledWhen', {
+    boolLogic: BoolLogic<any>;
+}, boolean>;
+
+/**
+ * Read-only condition concern
+ *
+ * Evaluates a boolean logic expression to determine if a field should be read-only.
+ * Automatically tracks all state paths accessed in the condition.
+ *
+ * Returns true if read-only, false if editable.
+ *
+ * @example
+ * ```typescript
+ * store.useConcerns('my-concerns', {
+ *   'productId': {
+ *     readonlyWhen: { boolLogic: { IS_EQUAL: ['order.status', 'completed'] } }
+ *   }
+ * })
+ * // Returns: true if order status is 'completed', false otherwise
+ * ```
+ */
+
+declare const readonlyWhen: ConcernType<'readonlyWhen', {
+    boolLogic: BoolLogic<any>;
+}, boolean>;
+
+/**
+ * Visibility condition concern
+ *
+ * Evaluates a boolean logic expression to determine if a field should be visible.
+ * Automatically tracks all state paths accessed in the condition.
+ *
+ * Returns true if visible, false if hidden.
+ *
+ * @example
+ * ```typescript
+ * store.useConcerns('my-concerns', {
+ *   'advancedOptions': {
+ *     visibleWhen: { boolLogic: { IS_EQUAL: ['settings.mode', 'advanced'] } }
+ *   }
+ * })
+ * // Returns: true if settings.mode is 'advanced', false otherwise
+ * ```
+ */
+
+declare const visibleWhen: ConcernType<'visibleWhen', {
+    boolLogic: BoolLogic<any>;
+}, boolean>;
+
+/**
+ * Dynamic label template concern
+ *
+ * Interpolates a template string with values from state.
+ * Automatically tracks all state paths referenced in the template.
+ *
+ * Returns the interpolated string.
+ *
+ * @example
+ * ```typescript
+ * store.useConcerns('my-concerns', {
+ *   'priceField': {
+ *     dynamicLabel: { template: "Price: ${{product.price}}" }
+ *   }
+ * })
+ * // Result: "Price: $99.99"
+ * ```
+ */
+
+declare const dynamicLabel: ConcernType<'dynamicLabel', {
+    template: string;
+}, string>;
+
+/**
+ * Dynamic placeholder template concern
+ *
+ * Interpolates a template string with values from state.
+ * Automatically tracks all state paths referenced in the template.
+ *
+ * Returns the interpolated string.
+ *
+ * @example
+ * ```typescript
+ * store.useConcerns('my-concerns', {
+ *   'inputField': {
+ *     dynamicPlaceholder: { template: "Enter {{field.name}}" }
+ *   }
+ * })
+ * // Result: "Enter email address"
+ * ```
+ */
+
+declare const dynamicPlaceholder: ConcernType<'dynamicPlaceholder', {
+    template: string;
+}, string>;
+
+/**
+ * Dynamic tooltip template concern
+ *
+ * Interpolates a template string with values from state.
+ * Automatically tracks all state paths referenced in the template.
+ *
+ * Returns the interpolated string.
+ *
+ * @example
+ * ```typescript
+ * store.useConcerns('my-concerns', {
+ *   'strikePrice': {
+ *     dynamicTooltip: { template: "Strike at {{market.spot}}" }
+ *   }
+ * })
+ * // Result: "Strike at 105"
+ * ```
+ */
+
+declare const dynamicTooltip: ConcernType<'dynamicTooltip', {
+    template: string;
+}, string>;
+
+/**
+ * All pre-built concerns as a tuple (for use with findConcern)
+ */
+declare const prebuilts: readonly [ValidationStateConcern, ConcernType<"disabledWhen", {
+    boolLogic: BoolLogic<any>;
+}, boolean>, ConcernType<"readonlyWhen", {
+    boolLogic: BoolLogic<any>;
+}, boolean>, ConcernType<"visibleWhen", {
+    boolLogic: BoolLogic<any>;
+}, boolean>, ConcernType<"dynamicTooltip", {
+    template: string;
+}, string>, ConcernType<"dynamicLabel", {
+    template: string;
+}, string>, ConcernType<"dynamicPlaceholder", {
+    template: string;
+}, string>];
+/**
+ * Namespace style access for pre-builts
+ */
+declare const prebuiltsNamespace: {
+    validationState: ValidationStateConcern;
+    disabledWhen: ConcernType<"disabledWhen", {
+        boolLogic: BoolLogic<any>;
+    }, boolean>;
+    readonlyWhen: ConcernType<"readonlyWhen", {
+        boolLogic: BoolLogic<any>;
+    }, boolean>;
+    visibleWhen: ConcernType<"visibleWhen", {
+        boolLogic: BoolLogic<any>;
+    }, boolean>;
+    dynamicTooltip: ConcernType<"dynamicTooltip", {
+        template: string;
+    }, string>;
+    dynamicLabel: ConcernType<"dynamicLabel", {
+        template: string;
+    }, string>;
+    dynamicPlaceholder: ConcernType<"dynamicPlaceholder", {
+        template: string;
+    }, string>;
+};
+
+type index_ValidationError = ValidationError;
+type index_ValidationStateConcern = ValidationStateConcern;
+type index_ValidationStateInput<DATA, PATH extends DeepKey<DATA, Depth>, Depth extends number = DefaultDepth> = ValidationStateInput<DATA, PATH, Depth>;
+type index_ValidationStateResult = ValidationStateResult;
+declare const index_disabledWhen: typeof disabledWhen;
+declare const index_dynamicLabel: typeof dynamicLabel;
+declare const index_dynamicPlaceholder: typeof dynamicPlaceholder;
+declare const index_dynamicTooltip: typeof dynamicTooltip;
+declare const index_prebuilts: typeof prebuilts;
+declare const index_prebuiltsNamespace: typeof prebuiltsNamespace;
+declare const index_readonlyWhen: typeof readonlyWhen;
+declare const index_validationState: typeof validationState;
+declare const index_visibleWhen: typeof visibleWhen;
+declare namespace index {
+  export { type index_ValidationError as ValidationError, type index_ValidationStateConcern as ValidationStateConcern, type index_ValidationStateInput as ValidationStateInput, type index_ValidationStateResult as ValidationStateResult, index_disabledWhen as disabledWhen, index_dynamicLabel as dynamicLabel, index_dynamicPlaceholder as dynamicPlaceholder, index_dynamicTooltip as dynamicTooltip, index_prebuilts as prebuilts, index_prebuiltsNamespace as prebuiltsNamespace, index_readonlyWhen as readonlyWhen, index_validationState as validationState, index_visibleWhen as visibleWhen };
+}
+
+/**
+ * Concern lookup by name
+ *
+ * @param name The concern name to look up
+ * @param concerns Optional array of concerns to search (defaults to prebuilts)
+ * @returns The concern definition, or undefined if not found
+ */
+declare const findConcern: (name: string, concerns?: readonly any[]) => ConcernType | undefined;
+/**
+ * Default concerns provided by apex-state
+ */
+declare const defaultConcerns: readonly [ValidationStateConcern, ConcernType<"disabledWhen", {
+    boolLogic: BoolLogic<any>;
+}, boolean>, ConcernType<"readonlyWhen", {
+    boolLogic: BoolLogic<any>;
+}, boolean>, ConcernType<"visibleWhen", {
+    boolLogic: BoolLogic<any>;
+}, boolean>, ConcernType<"dynamicTooltip", {
+    template: string;
+}, string>, ConcernType<"dynamicLabel", {
+    template: string;
+}, string>, ConcernType<"dynamicPlaceholder", {
+    template: string;
+}, string>];
+
+/**
+ * SideEffects type definition
+ *
+ * Configuration types for side effects passed to useSideEffects hook.
+ * Simple tuple-based API: [path1, path2]
+ */
+
+/**
+ * Clear path rule - "when trigger paths change, set target paths to null"
+ *
+ * Format: [triggers[], targets[], options?]
+ * - triggers: paths that activate the rule
+ * - targets: paths to set to null
+ * - expandMatch: if true, [*] in targets expands to ALL keys (not just matched key)
+ */
+type ClearPathRule<DATA extends object, Depth extends number = DefaultDepth> = [DeepKey<DATA, Depth>[], DeepKey<DATA, Depth>[], {
+    expandMatch?: boolean;
+}?];
+/**
+ * Side effects configuration for useSideEffects hook
+ *
+ * @example
+ * ```typescript
+ * useSideEffects('my-effects', {
+ *   syncPaths: [
+ *     ['user.email', 'profile.email'],
+ *   ],
+ *   flipPaths: [
+ *     ['isActive', 'isInactive'],
+ *   ],
+ *   aggregations: [
+ *     ['total', 'price1'],  // target <- source (target always first)
+ *     ['total', 'price2'],
+ *   ],
+ *   listeners: [
+ *     {
+ *       path: 'user.profile',  // Watch user.profile.* changes
+ *       scope: 'user.profile',  // Receive scoped state
+ *       fn: (changes, state) => {
+ *         // changes: [['name', 'Alice', {}]]  // RELATIVE to scope
+ *         // state: user.profile sub-object
+ *         return [['status', 'updated', {}]]  // Return SCOPED paths (relative to scope)
+ *       }
+ *     },
+ *     {
+ *       path: 'user.profile.name',  // Watch specific path
+ *       scope: null,                // Get full state
+ *       fn: (changes, state) => {
+ *         // changes: [['user.profile.name', 'Alice', {}]]  // FULL path
+ *         // state: full DATA object
+ *         return undefined
+ *       }
+ *     },
+ *     {
+ *       path: 'p.123.g.abc.data.strike',  // Watch deep path
+ *       scope: 'p.123.g.abc',              // Get parent scope
+ *       fn: (changes, state) => {
+ *         // changes: [['data.strike', value, {}]]  // RELATIVE to scope
+ *         // state: p.123.g.abc object
+ *         return [['data.computed', computed, {}]]  // SCOPED path (relative to scope)
+ *       }
+ *     }
+ *   ]
+ * })
+ * ```
+ */
+interface SideEffects<DATA extends object, META extends GenericMeta = GenericMeta, Depth extends number = DefaultDepth> {
+    /**
+     * Sync paths - keeps specified paths synchronized
+     * Format: [path1, path2] - both paths stay in sync
+     * Accepts direct `SyncPair<T>[]` or pre-validated result from `syncPairs()`.
+     */
+    syncPaths?: SyncPair<DATA, Depth>[] | ValidatedSyncPairs<DATA>;
+    /**
+     * Flip paths - keeps specified paths with opposite values
+     * Format: [path1, path2] - paths have inverse boolean values
+     * Accepts direct `FlipPair<T>[]` or pre-validated result from `flipPairs()`.
+     */
+    flipPaths?: FlipPair<DATA, Depth>[] | ValidatedFlipPairs<DATA>;
+    /**
+     * Aggregations - aggregates sources into target
+     * Format: [target, source] - target is ALWAYS first (left)
+     * Multiple pairs can point to same target for multi-source aggregation
+     * Accepts direct `AggregationPair<T>[]` or pre-validated result from `aggregationPairs()`.
+     */
+    aggregations?: AggregationPair<DATA, Depth>[] | ValidatedAggregationPairs<DATA>;
+    /**
+     * Clear paths - "when X changes, set Y to null"
+     * Format: [triggers[], targets[], { expandMatch?: boolean }?]
+     * - Default: [*] in target correlates with trigger's [*] (same key)
+     * - expandMatch: true → [*] in target expands to ALL keys
+     */
+    clearPaths?: ClearPathRule<DATA, Depth>[];
+    /**
+     * Computations - numeric reduction operations (SUM, AVG)
+     * Format: [operation, target, source] - target is computed from sources
+     * Multiple pairs can point to same target for multi-source computation
+     * Unidirectional: source → target only (writes to target are no-op)
+     * Accepts direct `ComputationPair<T>[]` or pre-validated result from `computationPairs()`.
+     */
+    computations?: ComputationPair<DATA, Depth>[] | ValidatedComputationPairs<DATA>;
+    /**
+     * Listeners - react to state changes with scoped state
+     * Accepts direct `ListenerRegistration<T>[]` or pre-validated result from `listeners()`.
+     */
+    listeners?: ListenerRegistration<DATA, META>[];
+}
+
+declare const createGenericStore: <DATA extends object, META extends GenericMeta = GenericMeta, CONCERNS extends readonly ConcernType<string, any, any>[] = typeof defaultConcerns>(config?: StoreConfig) => {
+    syncPairs: <T extends [Exclude<DeepKey<DATA, 20>, `${string}??`>, Exclude<DeepKey<DATA, 20>, `${string}??`>][]>(pairs: CheckSyncPairs<DATA, T, 20>) => ValidatedSyncPairs<DATA>;
+    flipPairs: <T extends [Exclude<DeepKey<DATA, 20>, `${string}??`>, Exclude<DeepKey<DATA, 20>, `${string}??`>][]>(pairs: CheckSyncPairs<DATA, T, 20>) => ValidatedFlipPairs<DATA>;
+    aggregationPairs: <T extends ([Exclude<DeepKey<DATA, 20>, `${string}??`>, Exclude<DeepKey<DATA, 20>, `${string}??`>] | [Exclude<DeepKey<DATA, 20>, `${string}??`>, Exclude<DeepKey<DATA, 20>, `${string}??`>, BoolLogic<DATA, 20>])[]>(pairs: CheckAggregationPairs<DATA, T, 20>) => ValidatedAggregationPairs<DATA>;
+    computationPairs: <T extends ([ComputationOp, DeepKeyFiltered<DATA, number, 20>, DeepKeyFiltered<DATA, number, 20>] | [ComputationOp, DeepKeyFiltered<DATA, number, 20>, DeepKeyFiltered<DATA, number, 20>, BoolLogic<DATA, 20>])[]>(pairs: CheckComputationPairs<DATA, T, 20>) => ValidatedComputationPairs<DATA>;
+    listeners: <T extends readonly {
+        path: Exclude<DeepKey<DATA, 20>, `${string}??`> | null;
+        scope?: Exclude<DeepKey<DATA, 20>, `${string}??`> | null | undefined;
+        fn: (...args: any[]) => any;
+    }[]>(items: CheckListeners<DATA, META, T, 20>) => ValidatedListeners<DATA, META>;
+    Provider: {
+        (props: ProviderProps<DATA>): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    useFieldStore: <P extends DeepKey<DATA>>(path: P) => {
+        value: DeepValue<DATA, P>;
+        setValue: (newValue: DeepValue<DATA, P>, meta?: META) => void;
+    } & Record<string, unknown>;
+    useStore: <P extends DeepKey<DATA>>(path: P) => [DeepValue<DATA, P>, (value: DeepValue<DATA, P>, meta?: META) => void];
+    useJitStore: () => {
+        proxyValue: DATA;
+        setChanges: (changes: ArrayOfChanges<DATA, META>) => void;
+        getState: () => DATA;
+    };
+    useSideEffects: (id: string, effects: SideEffects<DATA, META>) => void;
+    useConcerns: <CUSTOM extends readonly ConcernType<string, any, any>[] = readonly []>(id: string, registration: ConcernRegistrationMap<DATA, readonly [...CONCERNS, ...CUSTOM]>, customConcerns?: CUSTOM) => void;
+    withConcerns: <SELECTION extends Partial<Record<Extract<CONCERNS[number], {
+        name: string;
+    }>["name"], boolean>>>(selection: SELECTION) => {
+        useFieldStore: <P extends DeepKey<DATA>>(path: P) => {
+            value: DATA extends readonly any[] ? DATA[number] : P extends `${infer First}.${infer Rest}` ? First extends keyof DATA ? DeepValue<NonNullable<DATA[First]>, Rest> : string extends keyof DATA ? First extends "[*]" ? DeepValue<DATA[keyof DATA & string], Rest> : unknown : unknown : P extends "[*]" ? string extends keyof DATA ? DATA[keyof DATA & string] : unknown : P extends keyof DATA ? DATA[P] : unknown;
+            setValue: (newValue: DATA extends readonly any[] ? DATA[number] : P extends `${infer First}.${infer Rest}` ? First extends keyof DATA ? DeepValue<NonNullable<DATA[First]>, Rest> : string extends keyof DATA ? First extends "[*]" ? DeepValue<DATA[keyof DATA & string], Rest> : unknown : unknown : P extends "[*]" ? string extends keyof DATA ? DATA[keyof DATA & string] : unknown : P extends keyof DATA ? DATA[P] : unknown, meta?: META) => void;
+        } & { [K in keyof SELECTION as SELECTION[K] extends true ? K : never]?: K extends keyof EvaluatedConcerns<CONCERNS> ? EvaluatedConcerns<CONCERNS>[K] : never; };
+    };
+    withMeta: (presetMeta: Partial<META>) => {
+        useFieldStore: <P extends DeepKey<DATA>>(path: P) => {
+            value: DeepValue<DATA, P>;
+            setValue: (newValue: DeepValue<DATA, P>, meta?: META) => void;
+        };
+    };
+};
+/** Return type of createGenericStore — used by testing mock for 1:1 type safety */
+type GenericStoreApi<DATA extends object, META extends GenericMeta = GenericMeta, CONCERNS extends readonly ConcernType<string, any, any>[] = typeof defaultConcerns> = ReturnType<typeof createGenericStore<DATA, META, CONCERNS>>;
+
+/**
+ * Minimal field interface that useBufferedField accepts
+ */
+interface FieldInput$2<T> {
+    value: T;
+    setValue: (v: T) => void;
+}
+/**
+ * Extended interface with buffering capabilities
+ */
+interface BufferedField<T> extends FieldInput$2<T> {
+    commit: () => void;
+    cancel: () => void;
+    isDirty: boolean;
+}
+/**
+ * Adds buffered editing to any field hook.
+ * Local changes are held until explicitly committed or cancelled.
+ *
+ * @param field - Field hook with { value, setValue }
+ * @returns Buffered field with commit/cancel/isDirty
+ *
+ * @example
+ * ```typescript
+ * const field = useFieldStore('user.name')
+ * const buffered = useBufferedField(field)
+ *
+ * // User types - updates local only
+ * buffered.setValue('new value')
+ *
+ * // Enter/Tab - commit to store
+ * buffered.commit()
+ *
+ * // Esc - revert to stored value
+ * buffered.cancel()
+ *
+ * // Check if user has unsaved changes
+ * if (buffered.isDirty) { ... }
+ * ```
+ */
+declare const useBufferedField: <T>(field: FieldInput$2<T>) => BufferedField<T>;
+
+/**
+ * Option for keyboard selection
+ */
+interface SelectOption<T> {
+    value: T;
+    label: string;
+}
+/**
+ * Configuration for keyboard select behavior
+ */
+interface KeyboardSelectConfig<T> {
+    /** Available options to select from */
+    options: SelectOption<T>[];
+    /** Time window to accumulate keystrokes (ms). Default: 500 */
+    debounceMs?: number;
+    /** Match from start of label only. Default: true */
+    matchFromStart?: boolean;
+}
+/**
+ * Minimal field interface that useKeyboardSelect accepts
+ */
+interface FieldInput$1<T> {
+    value: T;
+    setValue: (v: T) => void;
+}
+/**
+ * Adds keyboard-driven selection to any field hook.
+ * Typing letters auto-selects matching options.
+ *
+ * @param field - Field hook with { value, setValue, ...rest }
+ * @param config - Options and behavior configuration
+ * @returns Field with onKeyDown handler added
+ *
+ * @example
+ * ```typescript
+ * const field = useFieldStore('user.country')
+ * const { onKeyDown, ...rest } = useKeyboardSelect(field, {
+ *   options: [
+ *     { value: 'us', label: 'United States' },
+ *     { value: 'uk', label: 'United Kingdom' },
+ *     { value: 'ca', label: 'Canada' },
+ *   ]
+ * })
+ *
+ * // User types "u" -> selects "United States"
+ * // User types "un" quickly -> still "United States"
+ * // User types "c" -> selects "Canada"
+ *
+ * <input onKeyDown={onKeyDown} {...rest} />
+ * ```
+ */
+declare const useKeyboardSelect: <T, TField extends FieldInput$1<T>>(field: TField, config: KeyboardSelectConfig<T>) => TField & {
+    onKeyDown: (e: React.KeyboardEvent) => void;
+};
+
+/**
+ * Minimal field interface for throttling
+ * Supports setValue with optional additional arguments (e.g., meta)
+ */
+interface ThrottleFieldInput<T, Args extends unknown[] = unknown[]> {
+    value: T;
+    setValue: (v: T, ...args: Args) => void;
+}
+/**
+ * Throttle configuration
+ */
+interface ThrottleConfig {
+    /** Minimum milliseconds between setValue calls to the underlying field */
+    ms: number;
+}
+/**
+ * Adds throttling to any field hook.
+ * First setValue executes immediately, subsequent calls are rate-limited.
+ * Last value wins when multiple calls occur within the throttle window.
+ * Preserves the full setValue signature including additional arguments like meta.
+ *
+ * @param field - Field hook with { value, setValue, ...rest }
+ * @param config - Throttle configuration { ms }
+ * @returns Field with throttled setValue, plus any passthrough props
+ *
+ * @example
+ * ```typescript
+ * const field = useFieldStore('spotPrice')
+ * const throttled = useThrottledField(field, { ms: 100 })
+ *
+ * // Rapid updates from WebSocket
+ * throttled.setValue(1.234)  // Immediate
+ * throttled.setValue(1.235)  // Buffered
+ * throttled.setValue(1.236)  // Buffered (replaces 1.235)
+ * // After 100ms: 1.236 is applied
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With meta argument
+ * const field = useFieldStore('price')
+ * const throttled = useThrottledField(field, { ms: 100 })
+ * throttled.setValue(42, { source: 'websocket' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Composable with other wrappers
+ * const field = useFieldStore('price')
+ * const transformed = useTransformedField(field, {
+ *   to: (cents) => cents / 100,
+ *   from: (dollars) => Math.round(dollars * 100)
+ * })
+ * const throttled = useThrottledField(transformed, { ms: 50 })
+ * ```
+ */
+declare const useThrottledField: <T, Args extends unknown[] = unknown[], TField extends ThrottleFieldInput<T, Args> = ThrottleFieldInput<T, Args>>(field: TField, config: ThrottleConfig) => TField;
+
+/**
+ * Transform configuration for field values
+ */
+interface TransformConfig<TStored, TDisplay> {
+    /** Transform from stored value to display value */
+    to: (stored: TStored) => TDisplay;
+    /** Transform from display value to stored value */
+    from: (display: TDisplay) => TStored;
+}
+/**
+ * Minimal field interface that useTransformedField accepts
+ */
+interface FieldInput<T> {
+    value: T;
+    setValue: (v: T) => void;
+}
+/**
+ * Adds value transformation to any field hook.
+ * Converts between storage format and display format.
+ * Passes through any additional properties from the input field.
+ *
+ * @param field - Field hook with { value, setValue, ...rest }
+ * @param config - Transform functions { to, from }
+ * @returns Field with transformed types, plus any passthrough props
+ *
+ * @example
+ * ```typescript
+ * const field = useFieldStore('user.birthdate')
+ * const formatted = useTransformedField(field, {
+ *   to: (iso) => format(new Date(iso), 'MM/dd/yyyy'),
+ *   from: (display) => parse(display, 'MM/dd/yyyy').toISOString()
+ * })
+ *
+ * // formatted.value is "01/15/2024"
+ * // formatted.setValue("01/20/2024") stores ISO string
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Works with buffered fields - passes through commit/cancel/isDirty
+ * const field = useFieldStore('price')
+ * const buffered = useBufferedField(field)
+ * const formatted = useTransformedField(buffered, {
+ *   to: (cents) => (cents / 100).toFixed(2),
+ *   from: (dollars) => Math.round(parseFloat(dollars) * 100)
+ * })
+ *
+ * formatted.setValue("15.99")  // local only
+ * formatted.commit()           // stores 1599
+ * ```
+ */
+declare const useTransformedField: <TStored, TDisplay, TField extends FieldInput<TStored>>(field: TField, config: TransformConfig<TStored, TDisplay>) => Omit<TField, "value" | "setValue"> & FieldInput<TDisplay>;
+
+/** Legacy JS implementation - uses JS graph structure */
+declare const registerFlipPair: <DATA extends object, META extends GenericMeta = GenericMeta>(store: StoreInstance<DATA, META>, path1: string & {}, path2: string & {}) => (() => void);
+
+/** Legacy JS implementation - uses JS listener maps and sorted paths */
+declare const registerListenerLegacy: <DATA extends object, META extends GenericMeta = GenericMeta>(store: StoreInstance<DATA, META>, registration: ListenerRegistration<DATA, META>) => (() => void);
+
+/**
+ * Legacy batch version of registerSyncPair. Adds all edges first, then computes
+ * initial sync changes across all final groups and calls processChanges once.
+ * This avoids cascading effect re-evaluations when registering many pairs.
+ */
+declare const registerSyncPairsBatch: <DATA extends object, META extends GenericMeta = GenericMeta>(store: StoreInstance<DATA, META>, pairs: [string & {}, string & {}][]) => (() => void);
+
+declare const registerSideEffects: <DATA extends object, META extends GenericMeta = GenericMeta>(store: StoreInstance<DATA, META>, id: string, effects: SideEffects<DATA, META>) => (() => void);
+
+declare const evaluateBoolLogic: <STATE extends object>(logic: BoolLogic<STATE>, state: STATE) => boolean;
+
+/**
+ * Template string interpolation utilities
+ *
+ * Core utility for interpolating state values into template strings.
+ * Used by concerns and side effects for dynamic text generation.
+ */
+/**
+ * Extract all {{path}} placeholders from a template string
+ *
+ * @param template The template string with {{path}} placeholders
+ * @returns Array of path strings found in the template
+ *
+ * @example
+ * extractPlaceholders("Hello {{user.name}}, you have {{count}} messages")
+ * // ["user.name", "count"]
+ */
+declare const extractPlaceholders: (template: string) => string[];
+/**
+ * Interpolate {{path}} placeholders with values from state
+ *
+ * Replaces {{path.to.value}} with actual values from state.
+ * Only replaces if value is a string, number, or boolean.
+ * Missing/null/undefined/object values leave the original {{path}} for debugging.
+ *
+ * @param template The template string with {{path}} placeholders
+ * @param state The state object to read values from
+ * @returns The interpolated string
+ *
+ * @example
+ * interpolateTemplate("Value is {{market.spot}}", state)
+ * // "Value is 105"
+ *
+ * @example
+ * interpolateTemplate("Hello {{user.name}}, missing: {{invalid.path}}", state)
+ * // "Hello Alice, missing: {{invalid.path}}"
+ */
+declare const interpolateTemplate: <STATE extends object>(template: string, state: STATE) => string;
+
+/**
+ * Deep access utilities for safe nested object access
+ *
+ * Uses native Reflect for reads (~2x faster) and writes (~3x faster) vs lodash.
+ * Maintains valtio reactivity when setting values.
+ */
+
+/**
+ * Unified namespace for dot notation path operations
+ *
+ * Provides type-safe and unsafe variants for working with nested objects
+ * using dot notation paths (e.g., 'user.address.city')
+ */
+declare const dot: {
+    get: <T extends object, P extends DeepKey<T>>(obj: T, path: P) => DeepValue<T, P>;
+    get__unsafe: <P extends string>(obj: unknown, path: P) => unknown;
+    set: <T extends object, P extends DeepKey<T>>(obj: T, path: P, value: DeepValue<T, P>) => void;
+    set__unsafe: <T extends object, P extends string>(obj: T, path: P, value: unknown) => void;
+    has: <T extends object, P extends DeepKey<T>>(obj: T, path: P) => boolean;
+    same: <T extends object, P extends string>(obj: T, ...paths: P[]) => boolean;
+};
+
+/**
+ * Hash key utilities
+ *
+ * Utilities for working with hash key notation in Record-based paths.
+ * Hash keys ([*]) are type-level markers for indexing into Records/HashMaps.
+ *
+ * @example
+ * ```typescript
+ * import { _, hashKey } from '@sladg/apex-state'
+ *
+ * // Use _ in template strings
+ * const path = `users.${_('u1')}.posts.${_('p1')}.name`
+ *
+ * // Use hashKey namespace for validation
+ * hashKey.rejectDynamic(path)
+ * ```
+ */
+
+/**
+ * Converts a concrete ID to hash key notation for inline template string usage
+ * Returns the concrete ID typed as HASH_KEY for Record/HashMap indexing
+ *
+ * @param id - The concrete ID (e.g., "u1", "p1", "c1")
+ * @returns The concrete ID typed as HASH_KEY
+ *
+ * @example
+ * ```typescript
+ * const path = `users.${_('u1')}.posts.${_('p1')}.name`
+ * // → "users.u1.posts.p1.name" (typed as containing HASH_KEY)
+ * ```
+ */
+declare const _: (id: string) => HASH_KEY;
+/**
+ * Hash key utilities namespace
+ *
+ * Provides utilities for working with hash keys in Record-based paths
+ */
+declare const hashKey: {
+    /** Reject paths with dynamic hash keys */
+    readonly rejectDynamic: <P extends string>(path: P) => void;
+    /** Alias for _ function */
+    readonly _: (id: string) => HASH_KEY;
+};
+
+/**
+ * Type checking utilities — similar to lodash type guards
+ *
+ * Provides type-safe predicates for common type checks with TypeScript support
+ */
+
+/**
+ * Unified namespace for type checking
+ *
+ * @example
+ * ```typescript
+ * import { is } from './utils/is'
+ *
+ * if (is.object(value)) { ... }
+ * if (is.array(value)) { ... }
+ * if (is.nil(value)) { ... }
+ *
+ * // Negated versions
+ * if (is.not.object(value)) { ... }
+ * if (is.not.array(value)) { ... }
+ * ```
+ */
+declare const is: {
+    nil: (value: unknown) => value is null | undefined;
+    undefined: (value: unknown) => value is undefined;
+    null: (value: unknown) => value is null;
+    object: (value: unknown) => value is Record<string, unknown>;
+    objectOrArray: (value: unknown) => value is Record<string, unknown> | unknown[];
+    array: (value: unknown) => value is unknown[];
+    string: (value: unknown) => value is string;
+    number: (value: unknown) => value is number;
+    boolean: (value: unknown) => value is boolean;
+    function: (value: unknown) => value is (...args: unknown[]) => unknown;
+    symbol: (value: unknown) => value is symbol;
+    date: (value: unknown) => value is Date;
+    regexp: (value: unknown) => value is RegExp;
+    numericKey: (value: string) => boolean;
+    primitive: (value: unknown) => value is Primitive;
+    empty: (value: unknown) => boolean;
+    equal: (a: unknown, b: unknown) => boolean;
+    not: {
+        nil: <T>(value: T | null | undefined) => value is T;
+        undefined: <T>(value: T | undefined) => value is T;
+        null: <T>(value: T | null) => value is T;
+        object: <T>(value: T) => value is Exclude<T, Record<string, unknown>>;
+        objectOrArray: <T>(value: T) => value is Exclude<T, Record<string, unknown> | unknown[]>;
+        array: <T>(value: T) => value is Exclude<T, unknown[]>;
+        string: <T>(value: T) => value is Exclude<T, string>;
+        number: <T>(value: T) => value is Exclude<T, number>;
+        boolean: <T>(value: T) => value is Exclude<T, boolean>;
+        function: <T>(value: T) => value is Exclude<T, (...args: unknown[]) => unknown>;
+        symbol: <T>(value: T) => value is Exclude<T, symbol>;
+        date: <T>(value: T) => value is Exclude<T, Date>;
+        regexp: <T>(value: T) => value is Exclude<T, RegExp>;
+        primitive: <T>(value: T) => value is Exclude<T, Primitive>;
+        empty: (value: unknown) => boolean;
+        equal: (a: unknown, b: unknown) => boolean;
+    };
+};
+
+/**
+ * Apply Changes Utility
+ *
+ * Applies an array of changes to an object, returning a new object.
+ */
+
+/**
+ * Applies changes to an object, returning a new object with changes applied.
+ * Does not mutate the original object.
+ *
+ * @param obj - Source object
+ * @param changes - Array of [path, value, meta] tuples
+ * @returns New object with changes applied
+ *
+ * @example
+ * ```typescript
+ * const state = { user: { name: 'Alice', age: 30 } }
+ * const changes: ArrayOfChanges<typeof state> = [
+ *   ['user.name', 'Bob', {}],
+ *   ['user.age', 31, {}],
+ * ]
+ *
+ * const newState = applyChangesToObject(state, changes)
+ * // newState: { user: { name: 'Bob', age: 31 } }
+ * // state is unchanged
+ * ```
+ */
+declare const applyChangesToObject: <T extends object>(obj: T, changes: ArrayOfChanges<T>) => T;
+
+/**
+ * Deep clone utility — single swap point for the cloning implementation.
+ *
+ * Uses @jsbits/deep-clone in "exact" mode which preserves:
+ * - Getter/setter property descriptors
+ * - Property attributes (enumerable, configurable, writable)
+ * - Prototypes
+ *
+ * Swap the implementation here to change cloning behavior everywhere.
+ */
+/**
+ * Deep clone an object, preserving getters, setters, and property descriptors.
+ * Returns a fully independent copy — mutations to the clone never affect the original.
+ *
+ * Throws if the input contains circular references.
+ */
+declare const deepClone: <T>(value: T) => T;
+
+export { type ValidationSchema as $, type Aggregation as A, type BoolLogic as B, type CheckAggregationPairs as C, type DefaultDepth as D, type EvaluatedConcerns as E, type ExtractEvaluateReturn as F, type GenericMeta as G, type FieldInput$2 as H, type FlipPair as I, type GenericStoreApi as J, type HASH_KEY as K, type KeyboardSelectConfig as L, type ListenerRegistration as M, type ProviderProps as N, type OnStateListener as O, type PathsWithSameValueAs as P, type SideEffects as Q, type ResolvableDeepKey as R, type SelectOption as S, type StoreConfig as T, type StoreInstance as U, type ValidatedAggregationPairs as V, type SyncPair as W, type ThrottleConfig as X, type ThrottleFieldInput as Y, type TransformConfig as Z, type ValidationError as _, type ComputationOp as a, type ValidationStateConcern as a0, type ValidationStateInput as a1, type ValidationStateResult as a2, _ as a3, applyChangesToObject as a4, createGenericStore as a5, deepClone as a6, defaultConcerns as a7, dot as a8, evaluateBoolLogic as a9, extractPlaceholders as aa, findConcern as ab, hashKey as ac, interpolateTemplate as ad, is as ae, index as af, registerFlipPair as ag, registerListenerLegacy as ah, registerSideEffects as ai, registerSyncPairsBatch as aj, useBufferedField as ak, useKeyboardSelect as al, useThrottledField as am, useTransformedField as an, type DeepKeyFiltered as b, type CheckComputationPairs as c, type ValidatedComputationPairs as d, type CheckSyncPairs as e, type ValidatedFlipPairs as f, type CheckListeners as g, type ValidatedListeners as h, type ValidatedSyncPairs as i, type AggregationPair as j, type ArrayOfChanges as k, type BaseConcernProps as l, type BufferedField as m, type CheckPairValueMatch as n, type ClearPathRule as o, type ComputationPair as p, type ConcernRegistration as q, type ConcernRegistrationMap as r, type ConcernType as s, type DebugConfig as t, type DebugTrack as u, type DebugTrackEntry as v, type DeepKey as w, type DeepPartial as x, type DeepRequired as y, type DeepValue as z };