@wildgrowth/voltix 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+First release of `@wildgrowth/voltix`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WILDGROWTH LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+<div align="center">
+
+# ⚡ Voltix
+
+**Fastest React state library.**
+
+[![CI](https://github.com/wildgrowth-oss/voltix/actions/workflows/ci.yml/badge.svg)](https://github.com/wildgrowth-oss/voltix/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@wildgrowth/voltix?color=8b5cf6)](https://www.npmjs.com/package/@wildgrowth/voltix)
+[![gzip](https://img.shields.io/badge/gzip-5.0%20KB-06b6d4)](https://bundlephobia.com/package/@wildgrowth/voltix)
+[![types](https://img.shields.io/npm/types/@wildgrowth/voltix?color=3178c6)](https://www.npmjs.com/package/@wildgrowth/voltix)
+[![license](https://img.shields.io/badge/license-MIT-64748b)](./LICENSE)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-22d3ee)](https://github.com/wildgrowth-oss/voltix/pulls)
+
+[Website](https://voltix.pages.dev) · [npm](https://www.npmjs.com/package/@wildgrowth/voltix) · [GitHub](https://github.com/wildgrowth-oss/voltix) · [Docs](./docs) · [Benchmarks](#benchmarks)
+
+</div>
+
+Voltix is a **~5.0 KB** global store for React with per-key subscriptions: set one field and only the components reading that field re-render. There is no provider to set up and there are no selector functions to write. Stores compose into a tree of nested stores and per-id lookups. Full TypeScript inference, zero dependencies, and the fastest update throughput of any React store we've measured.
+
+```tsx
+import { createStore, useStoreKey } from '@wildgrowth/voltix';
+
+const store = createStore({ count: 0 });
+
+function Counter() {
+  const count = useStoreKey(store, 'count');
+  return <button onClick={() => store.increment('count')}>{count}</button>;
+}
+```
+
+## Why Voltix
+
+- **Surgical re-renders.** Subscriptions are per key. Updating `x` never touches a component reading `y`, even when they share a store.
+- **Direct values.** `useStoreKey(store, 'count')` returns the value itself.
+- **Composes into a tree.** A key can hold another store or a lookup (a store per id); step into children with `select(key)`, into lookups with `at(id)`. Composition adds no cost to reads or writes.
+- **Identity-stable state.** `get()` returns the same object across writes, and the update path is the fastest of the group (see below).
+- **Fully typed, inference-first.** Keys, values, selectors, and equality functions are all inferred from your store. Selecting a key that doesn't exist is a compile error.
+- **Runtime contracts.** Put a zod (or valibot/arktype) schema on a key. Invalid writes are rejected, initial state included, and `onSchemaError` routes failures into your UI. Standard Schema keeps it dependency-free.
+- **Batteries included.** Action helpers, derived keys, write interceptors, persistence (sync + async), and an ESLint rule ship in the box.
+- **Tiny and dependency-free.** ~5.0 KB gzipped, tree-shakeable, `react` as the only peer.
+
+## Benchmarks
+
+Update throughput vs the latest Preact Signals, Zustand, nanostores, Solid, Valtio, Jotai and Legend-State (vanilla store engines, ops/sec, higher is faster). Each case runs in its own process and reports the median of 40 runs:
+
+| operation | **Voltix** | Preact Signals | Zustand | nanostores | Solid | Valtio | Jotai | Legend-State |
+|---|---|---|---|---|---|---|---|---|
+| update a value + notify | **187.8M** | 47.4M | 39.1M | 31.0M | 13.1M | 6.7M | 2.7M | 2.7M |
+| functional update (`x => x + 1`) | **192.0M** | 49.4M | 37.8M | 30.3M | 13.7M | 6.5M | 2.3M | 2.7M |
+| fine-grained update (1 of 1000) | **184.2M** | 47.9M | 39.1M | 30.4M | 12.5M | 161K | 2.6M | 1.1M |
+| notify 1000 subscribers | **563K** | 35K | 232K | 111K | 24K | — | 64K | 35K |
+
+Run `npm run bench` to reproduce ([`bench/vs.ts`](bench/vs.ts); Node 25, Apple M4 Pro). The gap matters under high write rates: drag interactions, streaming data, animation, and large grids of independently updating cells.
+
+## Install
+
+```bash
+npm i @wildgrowth/voltix
+```
+
+## The idea: fine-grained by key
+
+You subscribe to **keys**. A write to a key notifies exactly the components reading it, and leaves the rest untouched.
+
+```tsx
+const store = createStore({ user: { name: 'Ada' }, theme: 'dark', unread: 3 });
+
+function Unread() {
+  const unread = useStoreKey(store, 'unread'); // re-renders only when `unread` changes
+  return <span>{unread}</span>;
+}
+
+store.setKey('theme', 'light'); // <Unread /> does not re-render
+store.increment('unread');       // <Unread /> re-renders, nothing else does
+```
+
+Need several keys in one component? `useStoreSelector` subscribes to each and returns a slice:
+
+```tsx
+const { name, theme } = useStoreSelector(store, ['user', 'theme']);
+```
+
+## Composition: nesting and lookups
+
+A key holding another store becomes a child, reached with `select(key)`. `createLookup(factory)` makes a **lookup**: a store per id, created on first use. Updating one store re-renders only its readers. The factory can return a fully built store (schema, actions, `onSchemaError` attached) and the lookup keeps exactly that store.
+
+```tsx
+const app = createStore({
+  theme: 'dark',
+  profile: createStore({ name: 'Ada', age: 30 }),                   // nested store
+  todos: createLookup((id: string) => ({ text: '', done: false })), // lookup
+});
+
+app.setKey('theme', 'light');
+app.select('profile').setKey('age', 31);
+app.select('todos').at('t1').toggle('done');
+app.select('todos').keys(); // ['t1']
+```
+
+`select` takes one child key, `at` takes one id, and they chain for depth. See [Composition](./docs/composition.md).
+
+## Derived state
+
+`derive` computes a key from other keys in the same update; subscribers wake only when the result changes:
+
+```tsx
+const store = createStore({ first: 'Ada', last: 'Lovelace', full: '' });
+store.derive('full', ['first', 'last'], ({ first, last }) => `${first} ${last}`);
+```
+
+## API at a glance
+
+| | |
+|---|---|
+| `createStore(shape, options?)` | Create a store |
+| `createLookup(factory, options?)` | A map from id to store, populated lazily |
+| `select(key)` · `at(id)` | Step into a child · step into a lookup by id |
+| `createActions(store, define)` | Define a store's actions in one block, returned as a plain object |
+| `options.schema` | Per-key runtime contracts (zod, valibot, arktype) |
+| `onSchemaError(handler)` | React to a rejected write, with access to your actions |
+| `useStoreKey(store, key)` | Subscribe to one key, get the value directly |
+| `useStoreSelector(store, [keys])` | Subscribe to several keys, get a slice |
+| `createStoreHook(store)` | Pre-bind a typed hook to a store |
+| `set` · `setKey` · `update` · `increment` · `toggle` | Write helpers |
+| `mergeSet` · `batch` · `reset` · `derive` · `pick` | Object updates, batching, reset, computed keys, snapshots |
+| `subscribe` · `onChange` · `intercept` | Outside-React reactions and interception |
+| `options.equals` | Per-key custom equality (compare by `.id`, etc.) |
+
+Full reference in the [docs](./docs).
+
+## ESLint rule
+
+The package includes an ESLint rule (at `@wildgrowth/voltix/eslint`) that flags selector keys you never use. Requires ESLint 9+ (flat config):
+
+```js
+// eslint.config.js
+import voltix from '@wildgrowth/voltix/eslint';
+
+export default [{
+  plugins: { voltix },
+  rules: { 'voltix/no-unused-selector-keys': 'warn' },
+}];
+```
+
+## Documentation
+
+- [Getting started](./docs/getting-started.md)
+- [Walkthrough](./docs/walkthrough.md) — one app, from a single store to a composed tree
+- [Core concepts](./docs/core-concepts.md)
+- [Composition](./docs/composition.md) — nesting stores and per-id lookups
+- [API reference](./docs/api-reference.md)
+- [Guides](./docs/guides.md) — actions, contracts, derived state, middleware, persistence
+- [Patterns](./docs/patterns.md) — sending requests, polled live updates, live tables
+- [Comparison](./docs/comparison.md)
+
+## License
+
+MIT © WILDGROWTH LTD

package/dist/chunk-HGGX55FR.mjs

@@ -0,0 +1 @@
+var f=Object.defineProperty,g=Object.defineProperties;var h=Object.getOwnPropertyDescriptors;var d=Object.getOwnPropertySymbols;var i=Object.prototype.hasOwnProperty,j=Object.prototype.propertyIsEnumerable;var e=(c,a,b)=>a in c?f(c,a,{enumerable:!0,configurable:!0,writable:!0,value:b}):c[a]=b,k=(c,a)=>{for(var b in a||(a={}))i.call(a,b)&&e(c,b,a[b]);if(d)for(var b of d(a))j.call(a,b)&&e(c,b,a[b]);return c},l=(c,a)=>g(c,h(a));export{k as a,l as b};

package/dist/eslint.d.mts

@@ -0,0 +1,29 @@
+import { Rule } from 'eslint';
+
+/**
+ * ESLint rule: warn when a selector includes keys that are never destructured.
+ *
+ * Zero-config. Two detection paths:
+ * - `useStoreSelector(store, [...])` — recognized by name, checked strictly.
+ * - Any other `use*`-named hook called with a selector-style array (string keys /
+ *   `{ key: compareFn }` entries) whose result is destructured. To leave foreign
+ *   hooks alone, these only warn when at least one selected key IS destructured —
+ *   the overlap is the proof it's a selector call.
+ *
+ * Warnings require provability: the call's result must be destructured inline.
+ * A `...rest` element only counts as consuming the remaining keys when the rest
+ * variable is actually read somewhere; an unused rest is ignored. Anything short
+ * of proof is skipped rather than guessed at.
+ */
+declare const noUnusedSelectorKeys: Rule.RuleModule;
+declare const plugin: {
+    meta: {
+        name: string;
+    };
+    rules: {
+        'no-unused-selector-keys': Rule.RuleModule;
+    };
+    configs: Record<string, unknown>;
+};
+
+export { plugin as default, noUnusedSelectorKeys };

package/dist/eslint.d.ts

@@ -0,0 +1,29 @@
+import { Rule } from 'eslint';
+
+/**
+ * ESLint rule: warn when a selector includes keys that are never destructured.
+ *
+ * Zero-config. Two detection paths:
+ * - `useStoreSelector(store, [...])` — recognized by name, checked strictly.
+ * - Any other `use*`-named hook called with a selector-style array (string keys /
+ *   `{ key: compareFn }` entries) whose result is destructured. To leave foreign
+ *   hooks alone, these only warn when at least one selected key IS destructured —
+ *   the overlap is the proof it's a selector call.
+ *
+ * Warnings require provability: the call's result must be destructured inline.
+ * A `...rest` element only counts as consuming the remaining keys when the rest
+ * variable is actually read somewhere; an unused rest is ignored. Anything short
+ * of proof is skipped rather than guessed at.
+ */
+declare const noUnusedSelectorKeys: Rule.RuleModule;
+declare const plugin: {
+    meta: {
+        name: string;
+    };
+    rules: {
+        'no-unused-selector-keys': Rule.RuleModule;
+    };
+    configs: Record<string, unknown>;
+};
+
+export { plugin as default, noUnusedSelectorKeys };

package/dist/eslint.js

@@ -0,0 +1 @@
+"use strict";var d=Object.defineProperty;var k=Object.getOwnPropertyDescriptor;var v=Object.getOwnPropertyNames;var h=Object.prototype.hasOwnProperty;var b=(a,s)=>{for(var u in s)d(a,u,{get:s[u],enumerable:!0})},x=(a,s,u,c)=>{if(s&&typeof s=="object"||typeof s=="function")for(let t of v(s))!h.call(a,t)&&t!==u&&d(a,t,{get:()=>s[t],enumerable:!(c=k(s,t))||c.enumerable});return a};var R=a=>x(d({},"__esModule",{value:!0}),a);var S={};b(S,{default:()=>I,noUnusedSelectorKeys:()=>g});module.exports=R(S);var g={meta:{type:"problem",docs:{description:"Warn when a selector includes keys that are never destructured or used.",recommended:!0},schema:[],messages:{unusedKey:"'{{key}}' is selected but never destructured. Remove it from the selector, or destructure and use it."}},create(a){function s(t){let o=[];for(let e of t.elements)if(e){if(e.type==="Literal"&&typeof e.value=="string")o.push({node:e,name:e.value});else if(e.type==="ObjectExpression")for(let n of e.properties){if(n.type!=="Property"||n.computed)continue;let i=n.key.type==="Identifier"?n.key.name:n.key.type==="Literal"?String(n.key.value):null;i&&o.push({node:n.key,name:i})}}return o}function u(t,o){if(o.argument.type!=="Identifier")return!0;let e=o.argument.name,n=a.sourceCode.getDeclaredVariables(t).find(i=>i.name===e);return n?n.references.some(i=>i.isRead()):!0}function c(t,o,e){let n=t.parent;if(!n||n.type!=="VariableDeclarator"||n.id.type!=="ObjectPattern")return;let i=n.id,f=i.properties.find(r=>r.type==="RestElement");if(f&&u(n,f))return;let y=s(o);if(y.length===0)return;let l=new Set;for(let r of i.properties)r.type!=="Property"||r.computed||(r.key.type==="Identifier"?l.add(r.key.name):r.key.type==="Literal"&&l.add(String(r.key.value)));if(!(e&&!y.some(({name:r})=>l.has(r))))for(let{node:r,name:m}of y)l.has(m)||a.report({node:r,messageId:"unusedKey",data:{key:m}})}return{CallExpression(t){if(t.callee.type!=="Identifier")return;let o=t.callee.name;if(o==="useStoreSelector"){let e=t.arguments[1];(e==null?void 0:e.type)==="ArrayExpression"&&c(t,e,!1);return}if(/^use[A-Z0-9]/.test(o)){let e=t.arguments[0];(e==null?void 0:e.type)==="ArrayExpression"&&c(t,e,!0)}}}}},p={meta:{name:"voltix"},rules:{"no-unused-selector-keys":g},configs:{}};p.configs.recommended={plugins:{voltix:p},rules:{"voltix/no-unused-selector-keys":"warn"}};var I=p;0&&(module.exports={noUnusedSelectorKeys});

package/dist/eslint.mjs

@@ -0,0 +1 @@
+import"./chunk-HGGX55FR.mjs";var m={meta:{type:"problem",docs:{description:"Warn when a selector includes keys that are never destructured or used.",recommended:!0},schema:[],messages:{unusedKey:"'{{key}}' is selected but never destructured. Remove it from the selector, or destructure and use it."}},create(c){function p(n){let s=[];for(let e of n.elements)if(e){if(e.type==="Literal"&&typeof e.value=="string")s.push({node:e,name:e.value});else if(e.type==="ObjectExpression")for(let t of e.properties){if(t.type!=="Property"||t.computed)continue;let o=t.key.type==="Identifier"?t.key.name:t.key.type==="Literal"?String(t.key.value):null;o&&s.push({node:t.key,name:o})}}return s}function f(n,s){if(s.argument.type!=="Identifier")return!0;let e=s.argument.name,t=c.sourceCode.getDeclaredVariables(n).find(o=>o.name===e);return t?t.references.some(o=>o.isRead()):!0}function l(n,s,e){let t=n.parent;if(!t||t.type!=="VariableDeclarator"||t.id.type!=="ObjectPattern")return;let o=t.id,y=o.properties.find(r=>r.type==="RestElement");if(y&&f(t,y))return;let i=p(s);if(i.length===0)return;let a=new Set;for(let r of o.properties)r.type!=="Property"||r.computed||(r.key.type==="Identifier"?a.add(r.key.name):r.key.type==="Literal"&&a.add(String(r.key.value)));if(!(e&&!i.some(({name:r})=>a.has(r))))for(let{node:r,name:d}of i)a.has(d)||c.report({node:r,messageId:"unusedKey",data:{key:d}})}return{CallExpression(n){if(n.callee.type!=="Identifier")return;let s=n.callee.name;if(s==="useStoreSelector"){let e=n.arguments[1];(e==null?void 0:e.type)==="ArrayExpression"&&l(n,e,!1);return}if(/^use[A-Z0-9]/.test(s)){let e=n.arguments[0];(e==null?void 0:e.type)==="ArrayExpression"&&l(n,e,!0)}}}}},u={meta:{name:"voltix"},rules:{"no-unused-selector-keys":m},configs:{}};u.configs.recommended={plugins:{voltix:u},rules:{"voltix/no-unused-selector-keys":"warn"}};var g=u;export{g as default,m as noUnusedSelectorKeys};

package/dist/index.d.mts

@@ -0,0 +1,373 @@
+/**
+ * A write interceptor. Runs before an update commits: return a partial to replace
+ * the update, `false` to veto it, or nothing to pass it through unchanged.
+ */
+type Interceptor<T extends object> = (update: Partial<T>, state: T) => Partial<T> | false | void;
+/** One validation failure reported by a Standard Schema. */
+interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }> | undefined;
+}
+/** A successful Standard Schema validation: the (possibly transformed) value to use. */
+interface StandardSchemaSuccess<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+}
+/** A failed Standard Schema validation. */
+interface StandardSchemaFailure {
+    readonly issues: ReadonlyArray<StandardSchemaIssue>;
+}
+/**
+ * The Standard Schema interface (standardschema.dev) — the common contract implemented
+ * by zod (>=3.24), valibot (>=1.0), arktype (>=2.0), and others. Vendored as types only,
+ * so any conforming library plugs into {@link StoreOptions.schema} with no dependency here.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaSuccess<Output> | StandardSchemaFailure | Promise<unknown>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+}
+/** A rejected write, handed to handlers registered with {@link StoreType.onSchemaError}. */
+interface SchemaError<T extends object = any> {
+    /** The key whose write was vetoed. */
+    readonly key: keyof T;
+    /** What the schema objected to. */
+    readonly issues: ReadonlyArray<StandardSchemaIssue>;
+    /** The value that was rejected. */
+    readonly value: unknown;
+    /** The node that rejected it — for a lookup, the store at that id, not its parent. */
+    readonly store: StoreType<T>;
+}
+/** Options for {@link createStore}. */
+interface StoreOptions<T extends object> {
+    /**
+     * Per-key equality, fixed at creation. When a write would change a key, its
+     * function runs with (prev, next); returning `true` treats the values as equal
+     * and skips the update for that key.
+     */
+    equals?: {
+        [K in keyof T]?: (prev: T[K], next: T[K]) => boolean;
+    };
+    /**
+     * Per-key write contracts, as Standard Schemas (zod, valibot, arktype, …). A write
+     * to a key runs its schema first: issues veto that key's write (with readable
+     * errors in dev), and a transforming schema commits its parsed output. A schema's
+     * output type must match the key's type. Keys without a schema are untouched;
+     * stores without schemas skip validation entirely. Schemas are locked at creation.
+     */
+    schema?: {
+        [K in keyof T]?: StandardSchemaV1<any, T[K]>;
+    };
+}
+/** Keys of `T` whose value is a `number`. */
+type NumericKeys<T> = {
+    [K in keyof T]: T[K] extends number ? K : never;
+}[keyof T];
+/** Keys of `T` whose value is a `boolean`. */
+type BooleanKeys<T> = {
+    [K in keyof T]: T[K] extends boolean ? K : never;
+}[keyof T];
+/**
+ * A reactive store. The value returned by {@link createStore}. Hold it as
+ * a field to compose stores (`{ store: StoreType<CartState> }`), or pass it to
+ * {@link useStoreSelector} / {@link createStoreHook} to subscribe in React.
+ */
+interface StoreType<T extends object> {
+    /** Read the whole state (identity-stable until a `set` changes a key). */
+    get(): T;
+    /** Read one key. */
+    getKey<K extends keyof T>(key: K): T[K];
+    /** Shallow-merge a partial into state; notifies only the keys that changed. */
+    set(update: Partial<T>): void;
+    /** Set one key. */
+    setKey<K extends keyof T>(key: K, value: T[K]): void;
+    /** Set one key from its current value: `setKey(key, updater(prev))`. */
+    update<K extends keyof T>(key: K, updater: (prev: T[K]) => T[K]): void;
+    /** Add `amount` (default 1) to a numeric key. */
+    increment(key: NumericKeys<T>, amount?: number): void;
+    /** Flip a boolean key. */
+    toggle(key: BooleanKeys<T>): void;
+    /** Merge a partial into an object key and write the result. */
+    mergeSet<K extends keyof T>(key: K, value: T[K] extends object ? Partial<T[K]> : never): void;
+    /**
+     * Reset all keys (or the given keys) to the initial state. Stores without child
+     * nodes or schemas read from the original input object, which should not be mutated.
+     */
+    reset(keys?: (keyof T)[]): void;
+    /** Coalesce many sets inside `fn` into a single notification per subscription. */
+    batch(fn: () => void): void;
+    /** Subscribe to specific keys. Each call is independent, even with the same listener. Returns an unsubscribe. */
+    subscribe(keys: (keyof T)[], listener: () => void): () => void;
+    /** Imperative snapshot of specific keys. */
+    pick<K extends keyof T>(keys: K[]): Pick<T, K>;
+    /**
+     * Intercept writes before they commit. `fn` returns a partial to replace the
+     * update, `false` to veto it, or nothing to pass through. With `keys`, it runs
+     * only when the update touches one of them. Returns an unsubscribe.
+     */
+    intercept(fn: Interceptor<T>, keys?: (keyof T)[]): () => void;
+    /** React to key changes outside React, with the new and previous values. */
+    onChange<K extends keyof T>(keys: K[], callback: (values: Pick<T, K>, prev: Pick<T, K>) => void): () => void;
+    /**
+     * Derive `outKey` from `inputs`: `compute` runs inside any `set` that changes an
+     * input and commits its result in the same update, so subscribers to `outKey`
+     * wake only when the derived value changes. Returns a disposer.
+     */
+    derive<K extends keyof T, I extends keyof T>(outKey: K, inputs: I[], compute: (values: Pick<T, I>) => T[K]): () => void;
+    /**
+     * React to a write rejected by a key's schema. Registered after construction, so the
+     * handler can reach the finished store and its actions. Returns an unsubscribe.
+     * Handlers replace the default console reporting; the write stays vetoed either way.
+     */
+    onSchemaError(handler: (error: SchemaError<T>) => void): () => void;
+}
+/**
+ * Brand marking a value as a navigable node — a {@link Store} or a {@link Lookup} — so a
+ * parent `createStore` can tell a nested store from ordinary object state.
+ */
+declare const NODE: unique symbol;
+/** Type-level brand: any value that is a store or a lookup. */
+type NodeBrand = {
+    readonly [NODE]: 'store' | 'lookup';
+};
+/** Keys of `T` whose value is a nested store or lookup. */
+type ChildKey<T> = {
+    [K in keyof T]-?: NonNullable<T[K]> extends NodeBrand ? K : never;
+}[keyof T];
+/** Keys of `T` that hold ordinary reactive state. */
+type LeafKey<T> = Exclude<keyof T, ChildKey<T>>;
+/** The flat reactive state of a composed store (its non-node keys). */
+type LeafState<T> = {
+    [K in LeafKey<T>]: T[K];
+};
+/**
+ * A store that may hold other nodes. Ordinary keys are reactive leaves driven by the fast
+ * mutate-in-place engine; a key whose value is another {@link Store} or {@link Lookup} is a
+ * child, reached with {@link Store.select}. Build one with {@link createStore}.
+ */
+interface Store<T extends object> extends StoreType<LeafState<T>> {
+    readonly [NODE]: 'store';
+    /** One structural step: the child node bound at `key` (a nested store or lookup). */
+    select<K extends ChildKey<T>>(key: K): T[K];
+    /** Names of this store's child keys. */
+    children(): ChildKey<T>[];
+}
+/**
+ * A map from id to store, populated lazily: the first {@link Lookup.at} for an id builds the
+ * store via the factory passed to {@link createLookup} and memoizes it. `S` is that store's
+ * type — exactly what the factory returns when it builds the store itself, or `Store<C>`
+ * when it returns a plain state shape.
+ */
+interface Lookup<Id extends PropertyKey, S extends object> {
+    readonly [NODE]: 'lookup';
+    /** The store at `id`, created on first access and memoized. Takes exactly one id. */
+    at(id: Id): S;
+    /** Whether a store for `id` currently exists. */
+    has(id: Id): boolean;
+    /** Drop the store at `id`. Returns whether it existed. */
+    remove(id: Id): boolean;
+    /** Live ids (insertion order). */
+    keys(): Id[];
+    /** Number of live stores. */
+    size(): number;
+    /** Drop every store. */
+    clear(): void;
+}
+/**
+ * Create a store from a state object. Ordinary keys are fast reactive leaves; a key whose
+ * value is another store or {@link Lookup} becomes a child, reached with `.select(key)`.
+ * The tree is wired once at creation; leaf reads and writes never traverse it, so update
+ * and notify throughput are unchanged.
+ *
+ * @example
+ * ```ts
+ * const settings = createStore({ theme: 'dark', fontSize: 14 });
+ * const workspace = createStore({ name: 'Personal', settings });
+ * workspace.setKey('name', 'Team');
+ * workspace.select('settings').setKey('fontSize', 16);
+ * ```
+ */
+declare function createStore<T extends object>(shape: T & {
+    readonly [NODE]?: never;
+}, options?: StoreOptions<LeafState<T>>): Store<T>;
+/**
+ * Create a {@link Lookup}: a map from id to store, populated lazily by `factory`.
+ *
+ * - `createLookup((id) => makeDocument(id))` — the factory builds each store itself
+ *   (schema, actions, error handlers already attached); the lookup memoizes exactly
+ *   that node.
+ * - `createLookup((id) => ({ ... }), options?)` — the factory returns a plain state
+ *   shape; the lookup builds a store per id, applying `options` to each one.
+ *
+ * @example
+ * ```ts
+ * const documents = createLookup((id: string) => ({ title: 'Untitled', body: '' }));
+ * documents.at('readme').setKey('title', 'README');
+ * documents.keys(); // ['readme']
+ * ```
+ */
+declare function createLookup<Id extends PropertyKey, N extends NodeBrand>(factory: (id: Id) => N): Lookup<Id, N>;
+declare function createLookup<Id extends PropertyKey, C extends object>(factory: (id: Id) => C & {
+    readonly [NODE]?: never;
+}, options?: StoreOptions<LeafState<C>>): Lookup<Id, Store<C>>;
+/**
+ * Define a set of actions for a store (or any node) and get them back as a plain,
+ * standalone object — the store itself is not modified. `define` receives the node,
+ * so actions close over it with full inference; since it takes any node, actions can
+ * reach across a composed tree with `select(key)` / `at(id)`.
+ *
+ * Actions are ordinary functions: export them beside the store, and combine sets
+ * with object spread when you want them split across files.
+ *
+ * @example
+ * ```ts
+ * const counter = createStore({ count: 0 });
+ * const counterActions = createActions(counter, (store) => ({
+ *   increment: () => store.increment('count'),
+ *   reset: () => store.reset(['count']),
+ * }));
+ * counterActions.increment();
+ * ```
+ */
+declare function createActions<S extends object, A extends object>(store: S, define: (store: S) => A): A;
+type PrimitiveKey<T extends object> = keyof T;
+type CompareFn<V> = (prev: V, next: V) => boolean;
+type KeySelector<T extends object> = PrimitiveKey<T>;
+type CustomSelector<T extends object> = {
+    [K in keyof T]?: CompareFn<T[K]>;
+};
+type SelectorInput<T extends object> = ReadonlyArray<KeySelector<T> | CustomSelector<T>>;
+type ExtractSelectorKeys<T extends object, S extends SelectorInput<T>> = {
+    [K in S[number] extends infer Item ? Item extends keyof T ? Item : keyof Item : never]: T[K];
+};
+type Picked<T extends object, S extends SelectorInput<T>> = ExtractSelectorKeys<T, S>;
+/**
+ * React hook that subscribes to specific keys in a store with fine-grained re-renders.
+ * Only re-renders when the selected keys actually change (using Object.is comparison).
+ *
+ * @param store - The store created with createStore
+ * @param selector - Array of keys to subscribe to, or objects with custom compare functions
+ * @returns Selected state values from the store
+ *
+ * @example
+ * ```ts
+ * // Subscribe to specific keys
+ * const { count, name } = useStoreSelector(store, ['count', 'name']);
+ *
+ * // Custom comparison for complex objects
+ * const { tasks } = useStoreSelector(store, [
+ *   { tasks: (prev, next) => prev.length === next.length }
+ * ]);
+ * ```
+ */
+declare function useStoreSelector<T extends object, S extends SelectorInput<T>>(store: StoreType<T>, selector: S): Picked<T, S>;
+/**
+ * React hook that subscribes to a single key and returns its value directly —
+ * the lean path for the common one-key case. Re-renders only when that key
+ * changes (Object.is, plus any store-level equality from options.equals).
+ * No wrapper object is allocated.
+ *
+ * @example
+ * ```ts
+ * const count = useStoreKey(store, 'count');
+ * ```
+ */
+declare function useStoreKey<T extends object, K extends keyof T>(store: StoreType<T>, key: K): T[K];
+/**
+ * Creates a pre-bound selector hook for a specific store instance.
+ * Infers the state type from the store — no manual generics needed.
+ *
+ * @param store - The store created with createStore
+ * @returns A React hook with the same API as useStoreSelector, but with the store already bound
+ *
+ * @example
+ * ```ts
+ * const useWorkspace = createStoreHook(workspace);
+ *
+ * // In a component:
+ * const { name, syncing } = useWorkspace(['name', 'syncing']);
+ * ```
+ */
+declare function createStoreHook<T extends object>(store: StoreType<T>): <S extends SelectorInput<T>>(selector: S) => Picked<T, S>;
+/**
+ * Shallow-merge helper: `{ ...base, ...patch }`, typed so the patch can only
+ * carry keys of the base. A plain function on plain data — pair it with a write
+ * when you want the result stored: `store.setKey('user', merge(user, patch))`,
+ * or reach for {@link StoreType.mergeSet} which does both in one call.
+ */
+declare function merge<T extends object>(base: T, patch: Partial<T>): T;
+/**
+ * Interface for synchronous storage (localStorage, sessionStorage, etc.).
+ */
+interface StorageSupportingInterface {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/**
+ * Interface for asynchronous storage (React Native AsyncStorage, etc.).
+ */
+interface AsyncStorageSupportingInterface {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+}
+type AnyStorage = Storage | StorageSupportingInterface | AsyncStorageSupportingInterface;
+/**
+ * Serialization used by {@link persist} and {@link loadPersistedState}.
+ * Any object with `stringify`/`parse` fits — `JSON` and superjson both do.
+ * Use the same parser on both sides.
+ */
+interface PersistParser {
+    stringify(value: any): string;
+    parse(text: string): any;
+}
+/**
+ * Persist selected keys of a store: each key is written to storage as it changes,
+ * under `${persistKey}:${keyName}`. Works with synchronous storage (localStorage,
+ * sessionStorage) and asynchronous storage (React Native AsyncStorage) — async
+ * writes are fire-and-forget, so a slow write never blocks the state update.
+ * Returns an unsubscribe that stops persisting.
+ *
+ * Seed the initial state with {@link loadPersistedState}, which reads the same keys.
+ *
+ * @example
+ * ```ts
+ * const persisted = loadPersistedState<State>(localStorage, 'myapp', ['theme']);
+ * const store = createStore<State>({ theme: 'light', ...persisted });
+ * persist(store, localStorage, 'myapp', ['theme']);
+ * ```
+ */
+declare function persist<T extends object>(store: StoreType<T>, storage: AnyStorage, persistKey: string, keys: (keyof T)[], parser?: PersistParser): () => void;
+/**
+ * Loads persisted state from individual key storage during store initialization.
+ * Reads keys saved by {@link persist} and returns them as partial state.
+ *
+ * Returns synchronously for sync storage and a Promise for async storage.
+ *
+ * @param storage - Storage interface to read from (same as passed to persist)
+ * @param persistKey - Base key prefix used for storage (same as passed to persist)
+ * @param keys - Array of keys to restore (should match the persisted keys)
+ * @returns Partial state object (sync) or Promise of partial state (async)
+ *
+ * @example
+ * ```ts
+ * // Sync — localStorage
+ * const persisted = loadPersistedState(localStorage, 'myapp', ['theme']);
+ * const store = createStore({ theme: 'light', ...persisted });
+ *
+ * // Async — React Native AsyncStorage
+ * const persisted = await loadPersistedState(AsyncStorage, 'myapp', ['theme']);
+ * const store = createStore({ theme: 'light', ...persisted });
+ * ```
+ */
+declare function loadPersistedState<T extends object>(storage: Storage | StorageSupportingInterface, persistKey: string, keys: (keyof T)[], parser?: PersistParser): Partial<T>;
+declare function loadPersistedState<T extends object>(storage: AsyncStorageSupportingInterface, persistKey: string, keys: (keyof T)[], parser?: PersistParser): Promise<Partial<T>>;
+
+export { type AsyncStorageSupportingInterface, type Lookup, type PersistParser, type SchemaError, type StandardSchemaFailure, type StandardSchemaIssue, type StandardSchemaSuccess, type StandardSchemaV1, type StorageSupportingInterface, type Store, type StoreOptions, type StoreType, createActions, createLookup, createStore, createStoreHook, loadPersistedState, merge, persist, useStoreKey, useStoreSelector };