@sladg/apex-state 3.0.1

package/dist/index.d.ts

@@ -0,0 +1,1527 @@
+import { ReactNode } from 'react';
+import { z } from 'zod';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * 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.
+ *
+ * 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"
+ * ```
+ */
+
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+type IsAny$1<T> = 0 extends 1 & T ? true : false;
+type DeepKey<T, Depth extends number = 20> = Depth extends 0 ? never : IsAny$1<T> extends true ? never : T extends Primitive ? never : T extends readonly any[] ? never : string extends keyof T ? HASH_KEY | (T[string] extends Primitive ? never : T[string] extends readonly any[] ? never : DeepKey<T[string], Prev<Depth>> extends infer DK ? DK extends string ? `${HASH_KEY}.${DK}` : never : never) : {
+    [K in keyof T & (string | number)]: `${K & string}` | (T[K] extends Primitive ? never : T[K] extends readonly any[] ? never : DeepKey<T[K], Prev<Depth>> extends infer DK ? DK extends string ? `${K & string}.${DK}` : never : never);
+}[keyof T & (string | number)];
+type Prev<N extends number> = N extends 20 ? 19 : N extends 19 ? 18 : N extends 18 ? 17 : N extends 17 ? 16 : N extends 16 ? 15 : N extends 15 ? 14 : N extends 14 ? 13 : N extends 13 ? 12 : N extends 12 ? 11 : N extends 11 ? 10 : N extends 10 ? 9 : N extends 9 ? 8 : N extends 8 ? 7 : N extends 7 ? 6 : N extends 6 ? 5 : N extends 5 ? 4 : N extends 4 ? 3 : N extends 3 ? 2 : N extends 2 ? 1 : N extends 1 ? 0 : never;
+
+/**
+ * Boolean logic DSL type definitions
+ *
+ * Type-safe conditional expression DSL used by concerns and side effects
+ * for reactive condition checking against state.
+ */
+
+/**
+ * Primitive types that can be compared in BoolLogic expressions
+ */
+type ComparableValue = string | number | boolean | null | undefined;
+/**
+ * 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
+ * - 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
+ * - IN: Check if path value is in allowed list
+ *
+ * @example
+ * ```typescript
+ * // Simple equality check
+ * const isAdmin: BoolLogic<State> = { IS_EQUAL: ['user.role', 'admin'] }
+ *
+ * // Combined conditions
+ * const canEdit: BoolLogic<State> = {
+ *   AND: [
+ *     { IS_EQUAL: ['user.role', 'editor'] },
+ *     { EXISTS: 'document.id' },
+ *     { NOT: { IS_EQUAL: ['document.status', 'locked'] } }
+ *   ]
+ * }
+ *
+ * // Numeric comparison
+ * const isExpensive: BoolLogic<State> = { GT: ['product.price', 100] }
+ * ```
+ */
+type BoolLogic<STATE> = {
+    IS_EQUAL: [DeepKey<STATE>, ComparableValue];
+} | {
+    EXISTS: DeepKey<STATE>;
+} | {
+    IS_EMPTY: DeepKey<STATE>;
+} | {
+    AND: BoolLogic<STATE>[];
+} | {
+    OR: BoolLogic<STATE>[];
+} | {
+    NOT: BoolLogic<STATE>;
+} | {
+    GT: [DeepKey<STATE>, number];
+} | {
+    LT: [DeepKey<STATE>, number];
+} | {
+    GTE: [DeepKey<STATE>, number];
+} | {
+    LTE: [DeepKey<STATE>, number];
+} | {
+    IN: [DeepKey<STATE>, ComparableValue[]];
+};
+
+/**
+ * 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<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;
+
+/**
+ * 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;
+    /**
+     * 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];
+}[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.
+ */
+
+/**
+ * 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.
+ *
+ * Used as the `registration` parameter for `useConcerns` / `registerConcernEffects`.
+ * Each key is a `DeepKey<DATA>` path, and the value maps concern names to their config.
+ *
+ * @example
+ * ```typescript
+ * const registration: ConcernRegistrationMap<MyFormState> = {
+ *   email: { validationState: { schema: z.string().email() } },
+ *   name: { validationState: { schema: z.string().min(1) } },
+ * }
+ * ```
+ */
+type ConcernRegistrationMap<DATA extends object> = Partial<Record<DeepKey<DATA>, Partial<Record<string, unknown>>>>;
+
+/**
+ * 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.
+ */
+type DeepKeyFiltered<T, U> = {
+    [K in DeepKey<T>]: DeepValue<T, K> extends U ? K : never;
+}[DeepKey<T>];
+
+/**
+ * PathsOfSameValue - Type-safe path tuples for side effects
+ *
+ * Simple tuple-based API for syncPaths, flipPaths, and aggregations.
+ *
+ * @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 DeepKey<DATA>> = {
+    [K in DeepKey<DATA>]: DeepValue<DATA, K> extends DeepValue<DATA, PATH> ? DeepValue<DATA, PATH> extends DeepValue<DATA, K> ? K : never : never;
+}[DeepKey<DATA>];
+/**
+ * A tuple of two paths that must have the same value type.
+ * Format: [path1, path2]
+ *
+ * @example
+ * const pair: SyncPair<State> = ['user.email', 'profile.email']
+ */
+type SyncPair<DATA extends object> = {
+    [P1 in DeepKey<DATA>]: [P1, PathsWithSameValueAs<DATA, P1>];
+}[DeepKey<DATA>];
+/**
+ * A tuple of two paths for flip (alias for SyncPair)
+ * Format: [path1, path2]
+ *
+ * @example
+ * const pair: FlipPair<State> = ['isActive', 'isInactive']
+ */
+type FlipPair<DATA extends object> = SyncPair<DATA>;
+/**
+ * A tuple for aggregation: [target, source]
+ * First element (left) is ALWAYS the target (aggregated) path.
+ * Second element is a source path.
+ *
+ * Multiple pairs can point to same target for multi-source aggregation.
+ *
+ * @example
+ * // target <- source (target is always first/left)
+ * const aggs: AggregationPair<State>[] = [
+ *   ['total', 'price1'],
+ *   ['total', 'price2'],
+ * ]
+ */
+type AggregationPair<DATA extends object> = SyncPair<DATA>;
+
+/** 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) */
+type DeepPartial<T> = {
+    [K in keyof T]?: NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> | undefined : T[K] | undefined;
+};
+
+interface BaseConcernProps<STATE, PATH extends string> {
+    state: STATE;
+    path: PATH;
+    value: unknown;
+}
+interface ConcernType<EXTRA_PROPS = Record<string, unknown>, RETURN_TYPE = unknown> {
+    name: string;
+    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;
+}
+/** 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>;
+}
+/** Consolidated registration input for side effects (sync, flip, aggregation, clear, listeners). */
+interface SideEffectsRegistration {
+    registration_id: string;
+    sync_pairs?: [string, string][];
+    flip_pairs?: [string, string][];
+    aggregation_pairs?: [string, string][];
+    clear_paths?: {
+        triggers: string[];
+        targets: string[];
+    }[];
+    listeners?: {
+        subscriber_id: number;
+        topic_path: string;
+        scope_path: string;
+    }[];
+}
+/** Consolidated registration output from side effects registration. */
+interface SideEffectsResult {
+    sync_changes: Change[];
+    aggregation_changes: Change[];
+    registered_listener_ids: number[];
+}
+/** Consolidated registration input for concerns (BoolLogic, validators, and ValueLogic). */
+interface ConcernsRegistration {
+    registration_id: string;
+    bool_logics?: {
+        output_path: string;
+        tree_json: string;
+    }[];
+    validators?: {
+        validator_id: number;
+        output_path: string;
+        dependency_paths: string[];
+        scope: string;
+    }[];
+    value_logics?: {
+        output_path: string;
+        tree_json: string;
+    }[];
+}
+/** 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 Zod schemas (can't cross WASM boundary). */
+    validatorSchemas: Map<number, z.ZodSchema>;
+}
+
+/**
+ * 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. */
+type OnStateListener<DATA extends object = object, SUB_STATE = DATA, META extends GenericMeta = GenericMeta> = (changes: ArrayOfChanges<SUB_STATE, META>, state: SUB_STATE) => ArrayOfChanges<DATA, 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> {
+    /**
+     * Path to watch - only changes under this path will trigger the listener
+     * null = watch all top-level paths
+     */
+    path: DeepKey<DATA> | null;
+    /**
+     * Scope for state and changes presentation
+     * - 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> | 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;
+}
+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[];
+}
+type ValidationStateInput<SUB_STATE, PATH extends DeepKey<SUB_STATE>> = {
+    schema: z.ZodSchema<DeepValue<SUB_STATE, PATH>>;
+} | {
+    [SCOPE in DeepKey<SUB_STATE>]: {
+        scope: SCOPE;
+        schema: z.ZodSchema<DeepValue<SUB_STATE, SCOPE>>;
+    };
+}[DeepKey<SUB_STATE>];
+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;
+
+/**
+ * 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<{
+    boolLogic: BoolLogic<any>;
+}, boolean>, ConcernType<{
+    boolLogic: BoolLogic<any>;
+}, boolean>, ConcernType<{
+    boolLogic: BoolLogic<any>;
+}, boolean>, ConcernType<{
+    template: string;
+}, string>, ConcernType<{
+    template: string;
+}, string>, ConcernType<{
+    template: string;
+}, string>];
+
+declare const disabledWhen: ConcernType<{
+    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<{
+    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<{
+    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<{
+    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<{
+    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<{
+    template: string;
+}, string>;
+
+/**
+ * All pre-built concerns as a tuple (for use with findConcern)
+ */
+declare const prebuilts: readonly [ValidationStateConcern, ConcernType<{
+    boolLogic: BoolLogic<any>;
+}, boolean>, ConcernType<{
+    boolLogic: BoolLogic<any>;
+}, boolean>, ConcernType<{
+    boolLogic: BoolLogic<any>;
+}, boolean>, ConcernType<{
+    template: string;
+}, string>, ConcernType<{
+    template: string;
+}, string>, ConcernType<{
+    template: string;
+}, string>];
+/**
+ * Namespace style access for pre-builts
+ */
+declare const prebuiltsNamespace: {
+    validationState: ValidationStateConcern;
+    disabledWhen: ConcernType<{
+        boolLogic: BoolLogic<any>;
+    }, boolean>;
+    readonlyWhen: ConcernType<{
+        boolLogic: BoolLogic<any>;
+    }, boolean>;
+    visibleWhen: ConcernType<{
+        boolLogic: BoolLogic<any>;
+    }, boolean>;
+    dynamicTooltip: ConcernType<{
+        template: string;
+    }, string>;
+    dynamicLabel: ConcernType<{
+        template: string;
+    }, string>;
+    dynamicPlaceholder: ConcernType<{
+        template: string;
+    }, string>;
+};
+
+type index_ValidationError = ValidationError;
+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_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 };
+}
+
+/**
+ * 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> = [
+    DeepKey<DATA>[],
+    DeepKey<DATA>[],
+    {
+        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 FULL paths
+ *       }
+ *     },
+ *     {
+ *       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 [['some.value.elsewhere', computed, {}]]  // FULL path
+ *       }
+ *     }
+ *   ]
+ * })
+ * ```
+ */
+interface SideEffects<DATA extends object, META extends GenericMeta = GenericMeta> {
+    /**
+     * Sync paths - keeps specified paths synchronized
+     * Format: [path1, path2] - both paths stay in sync
+     */
+    syncPaths?: SyncPair<DATA>[];
+    /**
+     * Flip paths - keeps specified paths with opposite values
+     * Format: [path1, path2] - paths have inverse boolean values
+     */
+    flipPaths?: FlipPair<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
+     */
+    aggregations?: AggregationPair<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>[];
+    /**
+     * Listeners - react to state changes with scoped state
+     */
+    listeners?: ListenerRegistration<DATA, META>[];
+}
+
+declare const createGenericStore: <DATA extends object, META extends GenericMeta = GenericMeta, CONCERNS extends readonly any[] = typeof defaultConcerns>(config?: StoreConfig) => {
+    Provider: {
+        ({ initialState: rawInitialState, children, }: ProviderProps<DATA>): react_jsx_runtime.JSX.Element | null;
+        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: (id: string, registration: ConcernRegistrationMap<DATA>, customConcerns?: readonly ConcernType<any, any>[]) => void;
+    withConcerns: <SELECTION extends Partial<Record<string, 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<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<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 CONCERNS[number]["name"] ? EvaluatedConcerns<CONCERNS>[K] : never; };
+    };
+};
+
+/**
+ * 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>;
+    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;
+    primitive: (value: unknown) => value is string | number | boolean | symbol | bigint | null | undefined;
+    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: (value: unknown) => boolean;
+        array: (value: unknown) => boolean;
+        string: (value: unknown) => boolean;
+        number: (value: unknown) => boolean;
+        boolean: (value: unknown) => boolean;
+        function: (value: unknown) => boolean;
+        symbol: (value: unknown) => boolean;
+        date: (value: unknown) => boolean;
+        regexp: (value: unknown) => boolean;
+        primitive: (value: unknown) => boolean;
+        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;
+
+export { type Aggregation, type AggregationPair, type ArrayOfChanges, type BaseConcernProps, type BoolLogic, type BufferedField, type ConcernRegistration, type ConcernRegistrationMap, type ConcernType, type DebugConfig, type DebugTrack, type DebugTrackEntry, type DeepKey, type DeepKeyFiltered, type DeepPartial, type DeepRequired, type DeepValue, type EvaluatedConcerns, type ExtractEvaluateReturn, type FieldInput$2 as FieldInput, type FlipPair, type GenericMeta, type KeyboardSelectConfig, type ListenerRegistration, type OnStateListener, type PathsWithSameValueAs, type ProviderProps, type SelectOption, type SideEffects, type StoreConfig, type StoreInstance, type SyncPair, type ThrottleConfig, type TransformConfig, type ValidationError, type ValidationStateResult, _, applyChangesToObject, createGenericStore, defaultConcerns, dot, evaluateBoolLogic, extractPlaceholders, findConcern, hashKey, interpolateTemplate, is, index as prebuilts, registerFlipPair, registerListenerLegacy, registerSideEffects, registerSyncPairsBatch, useBufferedField, useKeyboardSelect, useThrottledField, useTransformedField };