@violetflux/kerros 0.1.8 → 0.2.0

package/README.md

@@ -88,14 +88,11 @@ function App() {
 
 ### Use the Store
 
-Pass a selector that returns the fields used by the component:
+Read the Store directly. Kerros automatically tracks the properties read while this component renders:
 
 ```tsx
 function TaskList() {
-  const { tasks, finishTask } = useTask(s => ({
-    tasks: s.tasks,
-    finishTask: s.finishTask,
-  }))
+  const { tasks, finishTask } = useTask()
 
   return (
     <ul>
@@ -110,7 +107,7 @@ function TaskList() {
 }
 ```
 
-Kerros shallowly compares the selector object's top-level fields. When those selected fields stay equal, other Store updates do not rerender `TaskList`. The selector can stay inline and does not need `useCallback`.
+Changing an unread field does not rerender `TaskList`. Property tracking follows object, array, and nested reads; it does not perform deep equality over the whole Store.
 
 ## Install
 
@@ -128,7 +125,7 @@ React 17, React 18, and React 19 are supported.
 - **Almost nothing new to learn** — reuse the React knowledge you already have; if you can write a custom Hook, you can write a Store
 - **Designed for flexible refactoring** — Stores and components use the same Hook API, so local state can become shared state with very little work
 - **Local and application-wide state** — Provider placement determines the Store scope, balancing flexibility with simplicity
-- **Avoid Context-wide rerenders** — Context carries a stable container and components rerender only when their selector result changes
+- **Avoid Context-wide rerenders** — Context carries a stable container and components rerender only when an observed value changes
 - **TypeScript support** — Store and selector types are inferred without duplicate declarations
 
 ## From state management to state sharing
@@ -141,7 +138,23 @@ Passing `value` and `onChange` through layer after layer damages component bound
 
 Sharing frequently changing state through React Context directly also causes repeated work: every Context value change rerenders all consumers. Kerros keeps Provider scoping and multiple instances, but Context carries only a stable container. Components subscribe through selectors and rerender only when their selected result changes.
 
-Kerros stays simple, lightweight, and reliable. Write local state as an ordinary Hook, share it only when necessary, use a Provider to set its scope, and use selectors to choose what each component observes.
+Kerros stays simple, lightweight, and reliable. Write local state as an ordinary Hook, share it only when necessary, use a Provider to set its scope, and let automatic tracking observe what each component reads.
+
+## Subscription modes
+
+The selector-free form is the default and usually the best starting point:
+
+```tsx
+const { count, setCount } = useCounter()
+```
+
+- `useStore()` automatically tracks object, array, and nested properties read during render.
+- `useStore(selector)` is the advanced path for derived values and measured hot spots. Its returned object's top-level fields are shallowly compared with `Object.is`.
+- `createStore(model, { tracking: false })` and `bindStore({ tracking: false })` make selector-free reads compare the complete Store at the top level instead.
+
+Primitive snapshots use `Object.is`. `Map`, `Set`, class instances, and other non-plain objects are treated as atomic references. Store and external Store snapshots must be immutable: publish a new reference for every observable change.
+
+Do not save, return, spread, serialize, or pass the complete selector-free result around. Read properties immediately, normally by destructuring. Effects and `useEffectEvent` may perform imperative reads from `useInstance()`, but rendered state must use the subscribed Store Hook; never expose an Effect Event as a public Store action.
 
 ## Multiple instances
 
@@ -167,7 +180,7 @@ A Store may call another Store directly. For example, a task Store can read the
 
 ```tsx
 function useTaskModel() {
-  const { user } = useAccount(s => ({ user: s.user }))
+  const { user } = useAccount()
   const [tasks, setTasks] = useState<Task[]>([])
 
   const addTask = (title: string) => {
@@ -227,12 +240,13 @@ const [useCounter, CounterProvider] = createStore(useCounterModel)
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
   useModel: (props: TProps) => TStore,
+  options?: { tracking?: boolean },
 ): readonly [StoreHook<TStore>, StoreProvider<TProps>]
 ```
 
 - `useModel` follows the Rules of Hooks
 - Provider props, excluding `children`, are passed to `useModel`
-- the returned Store Hook requires an object-returning selector
+- the returned Store Hook accepts either no argument for automatic tracking or an object-returning selector
 - using the Store Hook outside its matching Provider throws a clear error
 - Provider instances work with Strict Mode and server rendering
 
@@ -258,6 +272,24 @@ If the state begins in `useState`, `useReducer`, an SDK Hook, or another custom
 
 Kerros uses the official `use-sync-external-store` shim for React 17 and prefers React's native implementation in React 18 and 19. React Compiler is optional.
 
+## ESLint guardrails
+
+Install the separate type-aware plugin for the safest default usage:
+
+```sh
+npm install --save-dev @violetflux/eslint-plugin-kerros @typescript-eslint/parser
+```
+
+```js
+import kerros from '@violetflux/eslint-plugin-kerros'
+
+export default [kerros.configs.recommendedTypeChecked]
+```
+
+`recommendedTypeChecked` enables all 17 rules as errors and uses TypeScript `projectService`. Very large repositories may use `kerros.configs.fastTypeChecked`, which keeps type-aware Store recognition but disables the most expensive whole-program and deep analyses. See the [measured ESLint benchmark](https://github.com/violetflux/kerros/blob/main/benchmarks/eslint/RESULTS.md); the fast profile is a tradeoff, not an untyped fallback. The plugin analyzes complete TS/TSX files, not incomplete Markdown snippets.
+
+For maintainers, npm Trusted Publisher entries must be configured for both `@violetflux/kerros` and `@violetflux/eslint-plugin-kerros`. That npm-side configuration is the only release step outside this repository; CI checks and publishes the runtime first, then the plugin.
+
 ## Documentation
 
 - [Introduction](https://violetflux.github.io/kerros/guide/introduction)

package/README.zh-CN.md

@@ -80,14 +80,11 @@ function App() {
 
 ### 使用 Store
 
-给 `useTask` 传入 selector，只返回组件使用的字段：
+直接读取 Store。Kerros 会自动追踪组件渲染期间访问的属性：
 
 ```tsx
 function TaskList() {
-  const { tasks, finishTask } = useTask(s => ({
-    tasks: s.tasks,
-    finishTask: s.finishTask,
-  }))
+  const { tasks, finishTask } = useTask()
 
   return (
     <ul>
@@ -102,7 +99,7 @@ function TaskList() {
 }
 ```
 
-Kerros 会浅比较 selector 返回对象的顶层字段。只要这些选中字段保持不变，Store 的其他更新就不会让 `TaskList` 重渲染。selector 可以直接写在调用位置，不需要 `useCallback`。
+没有读取的字段发生变化时，`TaskList` 不会重渲染。自动追踪支持对象、数组和深层属性访问，不会对完整 Store 做深比较。
 
 ## 安装
 
@@ -120,7 +117,7 @@ Kerros 会浅比较 selector 返回对象的顶层字段。只要这些选中字
 - **几乎没有学习成本**：直接复用已有的 React 知识，你怎么写 custom Hook，就可以怎么写 Store
 - **为灵活重构而设计**：Store 和组件使用同一套 Hook API，可以近乎零成本地把组件局部状态转换成组件间共享状态
 - **同时支持局部状态和全局状态**：Provider 决定 Store 的作用域，在灵活和简单之间取得平衡
-- **解决 Context 的重复渲染问题**：Context 只传递稳定容器，selector 选择结果不变的组件不会重渲染
+- **解决 Context 的重复渲染问题**：Context 只传递稳定容器，组件观察到的值不变时不会重渲染
 - **优秀的 TypeScript 支持**：Store 和 selector 类型自动推断，不需要重复声明
 
 ## 从状态管理到状态共享
@@ -133,7 +130,23 @@ Kerros 想解决的问题更小，也更直接。它不发明新的数据结构
 
 直接用 React Context 共享变化频繁的状态也会带来重复渲染：Context value 每次变化，所有消费者都会更新。Kerros 保留 Provider 的作用域和多实例能力，但 Context 只传递稳定容器；组件通过 selector 订阅数据，只有选择结果变化时才重渲染。
 
-Kerros 简单、轻量、可靠。先把状态写成普通 Hook，需要共享时再交给 `createStore`；Provider 决定状态共享到哪里，selector 决定每个组件订阅什么。
+Kerros 简单、轻量、可靠。先把状态写成普通 Hook，需要共享时再交给 `createStore`；Provider 决定状态共享到哪里，自动追踪决定每个组件订阅什么。
+
+## 三种订阅模式
+
+不传 selector 是默认用法，也是多数场景的起点：
+
+```tsx
+const { count, setCount } = useCounter()
+```
+
+- `useStore()`：自动追踪渲染期间读取的对象、数组和深层属性。
+- `useStore(selector)`：用于高级派生值和经过测量的性能热点；Kerros 用 `Object.is` 浅比较 selector 返回对象的顶层字段。
+- `createStore(model, { tracking: false })` 或 `bindStore({ tracking: false })`：关闭自动追踪，无 selector 读取改为完整 Store 顶层浅比较。
+
+基础类型快照使用 `Object.is`。`Map`、`Set`、类实例及其他非普通对象按整体引用处理。Store 和 External Store 快照必须保持不可变：每次可观察变化都发布新引用。
+
+不要保存、返回、展开、序列化或传递无 selector 的完整结果；应立即读取属性，通常直接解构。Effect 与 `useEffectEvent` 可以通过 `useInstance()` 做命令式读取，但参与渲染的状态必须使用订阅 Hook；也不要把 Effect Event 暴露成公共 Store action。
 
 ## 多个实例
 
@@ -159,7 +172,7 @@ Kerros 简单、轻量、可靠。先把状态写成普通 Hook，需要共享
 
 ```tsx
 function useTaskModel() {
-  const { user } = useAccount(s => ({ user: s.user }))
+  const { user } = useAccount()
   const [tasks, setTasks] = useState<Task[]>([])
 
   const addTask = (title: string) => {
@@ -219,12 +232,13 @@ const [useCounter, CounterProvider] = createStore(useCounterModel)
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
   useModel: (props: TProps) => TStore,
+  options?: { tracking?: boolean },
 ): readonly [StoreHook<TStore>, StoreProvider<TProps>]
 ```
 
 - `useModel` 必须遵守 Hooks 规则
 - 除 `children` 外的 Provider props 会传给 `useModel`
-- Store Hook 必须接收一个返回对象的 selector
+- Store Hook 可不传参数使用自动追踪，也可传入返回对象的 selector
 - 在对应 Provider 外调用会抛出明确错误
 - 支持 Strict Mode、服务端渲染和 Provider 多实例
 
@@ -250,6 +264,24 @@ Provider 的 Context 只保存原 Store 实例，组件直接订阅它；Kerros
 
 React 17 使用官方 `use-sync-external-store` shim；React 18 和 19 可用时优先使用 React 原生实现。React Compiler 不是必需项。
 
+## ESLint 防护规则
+
+建议安装独立的类型感知插件，并默认使用最严格配置：
+
+```sh
+npm install --save-dev @violetflux/eslint-plugin-kerros @typescript-eslint/parser
+```
+
+```js
+import kerros from '@violetflux/eslint-plugin-kerros'
+
+export default [kerros.configs.recommendedTypeChecked]
+```
+
+`recommendedTypeChecked` 把全部 17 条规则设为 error，并启用 TypeScript `projectService`。超大型仓库可改用 `kerros.configs.fastTypeChecked`：它仍然通过类型识别真实 Kerros Hook，只关闭最昂贵的全程序与深层分析。请参考[真实 ESLint 压测](https://github.com/violetflux/kerros/blob/main/benchmarks/eslint/RESULTS.md)；fast 是性能取舍，不是不可靠的命名降级。插件首版只分析完整 TS/TSX 文件，不分析不完整 Markdown 代码块。
+
+维护者还需要分别为 `@violetflux/kerros` 和 `@violetflux/eslint-plugin-kerros` 配置 npm Trusted Publisher。这是唯一的仓库外发布步骤；仓库内工作流会先检查并发布运行库，再发布插件。
+
 ## 文档
 
 - [介绍](https://violetflux.github.io/kerros/zh/guide/introduction)

package/dist/index.cjs

@@ -1,14 +1,79 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let react = require("react");
+let proxy_compare = require("proxy-compare");
 let use_sync_external_store_shim_with_selector = require("use-sync-external-store/shim/with-selector");
+//#region src/tracking.ts
+const useStoreLayoutEffect$1 = typeof window === "undefined" ? react.useEffect : react.useLayoutEffect;
+/**
+* Subscribe through either an explicit selector, shallow snapshots, or render access tracking
+*/
+function useStoreValue(store, selector, tracking) {
+	const committedTracking = (0, react.useRef)(void 0);
+	const [proxyCache] = (0, react.useState)(() => /* @__PURE__ */ new WeakMap());
+	const [calibration, calibrate] = (0, react.useReducer)((previous, snapshot) => ({
+		snapshot,
+		version: (previous?.version ?? 0) + 1
+	}), void 0);
+	const selectSnapshot = (0, react.useCallback)((snapshot) => {
+		const currentSnapshot = calibration && Object.is(calibration.snapshot, snapshot) ? calibration.snapshot : snapshot;
+		return selector ? selector(currentSnapshot) : currentSnapshot;
+	}, [calibration, selector]);
+	const compareSelections = (0, react.useCallback)((previous, next) => {
+		if (selector || !tracking) return shallowEqual(previous, next);
+		const committed = committedTracking.current;
+		if (!committed) return Object.is(previous, next);
+		return !(0, proxy_compare.isChanged)(committed.snapshot, next, committed.affected, /* @__PURE__ */ new WeakMap());
+	}, [selector, tracking]);
+	const snapshot = (0, use_sync_external_store_shim_with_selector.useSyncExternalStoreWithSelector)(store.subscribe, store.getSnapshot, store.getSnapshot, selectSnapshot, compareSelections);
+	const affected = /* @__PURE__ */ new WeakMap();
+	const shouldTrack = !selector && tracking;
+	const value = shouldTrack ? (0, proxy_compare.createProxy)(snapshot, affected, proxyCache) : snapshot;
+	useStoreLayoutEffect$1(() => {
+		if (shouldTrack) {
+			const renderedSnapshot = snapshot;
+			committedTracking.current = {
+				affected,
+				snapshot: renderedSnapshot
+			};
+			const currentSnapshot = store.getSnapshot();
+			if ((0, proxy_compare.isChanged)(renderedSnapshot, currentSnapshot, affected, /* @__PURE__ */ new WeakMap())) calibrate(currentSnapshot);
+		}
+	}, [
+		affected,
+		shouldTrack,
+		snapshot,
+		store
+	]);
+	return value;
+}
+/**
+* Compare values by identity first and enumerable top-level fields second
+*/
+function shallowEqual(left, right) {
+	if (Object.is(left, right)) return true;
+	if (!isShallowComparable(left) || !isShallowComparable(right)) return false;
+	const leftKeys = Object.keys(left);
+	if (leftKeys.length !== Object.keys(right).length) return false;
+	return leftKeys.every((key) => Object.prototype.hasOwnProperty.call(right, key) && Object.is(left[key], right[key]));
+}
+/**
+* Narrow values before enumerable field comparison
+*/
+function isShallowComparable(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === Array.prototype;
+}
+//#endregion
 //#region src/index.tsx
 const useStoreLayoutEffect = typeof window === "undefined" ? react.useEffect : react.useLayoutEffect;
 /**
-* Create a selector-first React Store and its matching Provider
+* Create a React Store with automatic tracking and explicit selector support
 */
-function createStore(useModel) {
+function createStore(useModel, options) {
 	const StoreContext = (0, react.createContext)(void 0);
 	const storeName = useModel.name || "KerrosStore";
+	const tracking = options?.tracking ?? true;
 	/** Run the model Hook and publish its committed snapshot */
 	const StoreProvider = (props) => {
 		const { children, ...storeProps } = props;
@@ -20,29 +85,28 @@ function createStore(useModel) {
 	StoreProvider.displayName = `${storeName}Provider`;
 	StoreContext.displayName = `${storeName}Context`;
 	/** Select Store fields through the stable Provider container */
-	const useStore = (selector) => {
-		return useStoreSelector(useStoreContext(StoreContext), selector);
-	};
+	const useStore = ((selector) => {
+		return useStoreValue(useStoreContext(StoreContext), selector, tracking);
+	});
 	return [useStore, StoreProvider];
 }
-/**
-* Bind existing external Store instances to scoped React consumers
-*/
-function bindStore(name = "KerrosExternalStore") {
+function bindStore(nameOrOptions = "KerrosExternalStore", inputOptions) {
+	const name = typeof nameOrOptions === "string" ? nameOrOptions : "KerrosExternalStore";
+	const tracking = (typeof nameOrOptions === "string" ? inputOptions : nameOrOptions)?.tracking ?? true;
 	const StoreContext = (0, react.createContext)(void 0);
 	/** Provide one existing Store instance without copying its snapshot */
-	const StoreProvider = (props) => {
+	const StoreProvider = ((props) => {
 		const { children, store } = props;
 		return (0, react.createElement)(StoreContext.Provider, { value: store }, children);
-	};
+	});
 	StoreProvider.displayName = `${name}Provider`;
 	StoreContext.displayName = `${name}Context`;
 	/** Select snapshot fields directly from the bound external Store */
-	const useStore = (selector) => {
-		return useStoreSelector(useStoreContext(StoreContext), selector);
-	};
+	const useStore = ((selector) => {
+		return useStoreValue(useStoreContext(StoreContext), selector, tracking);
+	});
 	/** Read the exact Store instance bound to the current Provider */
-	const useInstance = () => useStoreContext(StoreContext);
+	const useInstance = (() => useStoreContext(StoreContext));
 	return [
 		useStore,
 		StoreProvider,
@@ -76,21 +140,6 @@ function useStoreContext(context) {
 	if (!store) throw new Error("Kerros store hook must be used within its matching Provider");
 	return store;
 }
-/**
-* Select fields directly from an external Store subscription
-*/
-function useStoreSelector(store, selector) {
-	return (0, use_sync_external_store_shim_with_selector.useSyncExternalStoreWithSelector)(store.subscribe, store.getSnapshot, store.getSnapshot, selector, shallowEqual);
-}
-/**
-* Compare selector objects by their enumerable top-level fields
-*/
-function shallowEqual(left, right) {
-	if (Object.is(left, right)) return true;
-	const leftKeys = Object.keys(left);
-	if (leftKeys.length !== Object.keys(right).length) return false;
-	return leftKeys.every((key) => Object.prototype.hasOwnProperty.call(right, key) && Object.is(left[key], right[key]));
-}
 //#endregion
 exports.bindStore = bindStore;
 exports.createStore = createStore;

package/dist/index.d.cts

@@ -1,13 +1,37 @@
 import { FC, PropsWithChildren } from "react";
 //#region src/index.d.ts
+declare const storeHookMarker: unique symbol;
+declare const storeInstanceHookMarker: unique symbol;
+declare const externalStoreProviderMarker: unique symbol;
+/** Store behavior options */
+interface StoreOptions {
+  /** Automatically track properties read by selector-free Store hooks */
+  tracking?: boolean;
+}
 /** Store selector returning an object compared with shallow equality */
 type StoreSelector<TStore, TSelection extends object> = (store: TStore) => TSelection;
 /** Hook used by consumers to select Store fields */
 interface StoreHook<TStore> {
+  /** Type-only Store hook identity */
+  readonly [storeHookMarker]: TStore;
+  (): TStore;
   <TSelection extends object>(selector: StoreSelector<TStore, TSelection>): TSelection;
 }
 /** Provider created for a Store hook */
 type StoreProvider<TProps> = FC<PropsWithChildren<TProps>>;
+/** Hook returning the exact external Store instance */
+interface StoreInstanceHook<TStore> {
+  /** Type-only Store instance hook identity */
+  readonly [storeInstanceHookMarker]: TStore;
+  (): TStore;
+}
+/** Provider carrying an existing external Store instance */
+type ExternalStoreProvider<TStore> = StoreProvider<{
+  store: TStore;
+}> & {
+  /** Type-only external Store Provider identity */
+  readonly [externalStoreProviderMarker]: TStore;
+};
 /** Existing external Store contract supported by bindStore */
 interface ExternalStore<TSnapshot> {
   /** Read the current immutable snapshot */
@@ -18,16 +42,15 @@ interface ExternalStore<TSnapshot> {
 /** Extract the snapshot exposed by an external Store */
 type ExternalStoreSnapshot<TStore> = TStore extends ExternalStore<infer TSnapshot> ? TSnapshot : never;
 /** React bindings created for an existing external Store type */
-type StoreBinding<TStore extends ExternalStore<TSnapshot>, TSnapshot = ExternalStoreSnapshot<TStore>> = readonly [StoreHook<TSnapshot>, StoreProvider<{
-  store: TStore;
-}>, () => TStore];
+type StoreBinding<TStore extends ExternalStore<TSnapshot>, TSnapshot = ExternalStoreSnapshot<TStore>> = readonly [StoreHook<TSnapshot>, ExternalStoreProvider<TStore>, StoreInstanceHook<TStore>];
 /**
- * Create a selector-first React Store and its matching Provider
+ * Create a React Store with automatic tracking and explicit selector support
  */
-declare function createStore<TStore, TProps = Record<never, never>>(useModel: (props: TProps) => TStore): readonly [StoreHook<TStore>, StoreProvider<TProps>];
+declare function createStore<TStore, TProps = Record<never, never>>(useModel: (props: TProps) => TStore, options?: StoreOptions): readonly [StoreHook<TStore>, StoreProvider<TProps>];
 /**
  * Bind existing external Store instances to scoped React consumers
  */
-declare function bindStore<TStore extends ExternalStore<TSnapshot>, TSnapshot = ExternalStoreSnapshot<TStore>>(name?: string): StoreBinding<TStore, TSnapshot>;
+declare function bindStore<TStore extends ExternalStore<TSnapshot>, TSnapshot = ExternalStoreSnapshot<TStore>>(options?: StoreOptions): StoreBinding<TStore, TSnapshot>;
+declare function bindStore<TStore extends ExternalStore<TSnapshot>, TSnapshot = ExternalStoreSnapshot<TStore>>(name?: string, options?: StoreOptions): StoreBinding<TStore, TSnapshot>;
 //#endregion
-export { ExternalStore, ExternalStoreSnapshot, StoreBinding, StoreHook, StoreProvider, StoreSelector, bindStore, createStore };
+export { ExternalStore, ExternalStoreSnapshot, StoreBinding, StoreHook, StoreOptions, StoreProvider, StoreSelector, bindStore, createStore };

package/dist/index.d.mts

@@ -1,13 +1,37 @@
 import { FC, PropsWithChildren } from "react";
 //#region src/index.d.ts
+declare const storeHookMarker: unique symbol;
+declare const storeInstanceHookMarker: unique symbol;
+declare const externalStoreProviderMarker: unique symbol;
+/** Store behavior options */
+interface StoreOptions {
+  /** Automatically track properties read by selector-free Store hooks */
+  tracking?: boolean;
+}
 /** Store selector returning an object compared with shallow equality */
 type StoreSelector<TStore, TSelection extends object> = (store: TStore) => TSelection;
 /** Hook used by consumers to select Store fields */
 interface StoreHook<TStore> {
+  /** Type-only Store hook identity */
+  readonly [storeHookMarker]: TStore;
+  (): TStore;
   <TSelection extends object>(selector: StoreSelector<TStore, TSelection>): TSelection;
 }
 /** Provider created for a Store hook */
 type StoreProvider<TProps> = FC<PropsWithChildren<TProps>>;
+/** Hook returning the exact external Store instance */
+interface StoreInstanceHook<TStore> {
+  /** Type-only Store instance hook identity */
+  readonly [storeInstanceHookMarker]: TStore;
+  (): TStore;
+}
+/** Provider carrying an existing external Store instance */
+type ExternalStoreProvider<TStore> = StoreProvider<{
+  store: TStore;
+}> & {
+  /** Type-only external Store Provider identity */
+  readonly [externalStoreProviderMarker]: TStore;
+};
 /** Existing external Store contract supported by bindStore */
 interface ExternalStore<TSnapshot> {
   /** Read the current immutable snapshot */
@@ -18,16 +42,15 @@ interface ExternalStore<TSnapshot> {
 /** Extract the snapshot exposed by an external Store */
 type ExternalStoreSnapshot<TStore> = TStore extends ExternalStore<infer TSnapshot> ? TSnapshot : never;
 /** React bindings created for an existing external Store type */
-type StoreBinding<TStore extends ExternalStore<TSnapshot>, TSnapshot = ExternalStoreSnapshot<TStore>> = readonly [StoreHook<TSnapshot>, StoreProvider<{
-  store: TStore;
-}>, () => TStore];
+type StoreBinding<TStore extends ExternalStore<TSnapshot>, TSnapshot = ExternalStoreSnapshot<TStore>> = readonly [StoreHook<TSnapshot>, ExternalStoreProvider<TStore>, StoreInstanceHook<TStore>];
 /**
- * Create a selector-first React Store and its matching Provider
+ * Create a React Store with automatic tracking and explicit selector support
  */
-declare function createStore<TStore, TProps = Record<never, never>>(useModel: (props: TProps) => TStore): readonly [StoreHook<TStore>, StoreProvider<TProps>];
+declare function createStore<TStore, TProps = Record<never, never>>(useModel: (props: TProps) => TStore, options?: StoreOptions): readonly [StoreHook<TStore>, StoreProvider<TProps>];
 /**
  * Bind existing external Store instances to scoped React consumers
  */
-declare function bindStore<TStore extends ExternalStore<TSnapshot>, TSnapshot = ExternalStoreSnapshot<TStore>>(name?: string): StoreBinding<TStore, TSnapshot>;
+declare function bindStore<TStore extends ExternalStore<TSnapshot>, TSnapshot = ExternalStoreSnapshot<TStore>>(options?: StoreOptions): StoreBinding<TStore, TSnapshot>;
+declare function bindStore<TStore extends ExternalStore<TSnapshot>, TSnapshot = ExternalStoreSnapshot<TStore>>(name?: string, options?: StoreOptions): StoreBinding<TStore, TSnapshot>;
 //#endregion
-export { ExternalStore, ExternalStoreSnapshot, StoreBinding, StoreHook, StoreProvider, StoreSelector, bindStore, createStore };
+export { ExternalStore, ExternalStoreSnapshot, StoreBinding, StoreHook, StoreOptions, StoreProvider, StoreSelector, bindStore, createStore };

package/dist/index.mjs

@@ -1,13 +1,78 @@
-import { createContext, createElement, useContext, useEffect, useLayoutEffect, useState } from "react";
+import { createContext, createElement, useCallback, useContext, useEffect, useLayoutEffect, useReducer, useRef, useState } from "react";
+import { createProxy, isChanged } from "proxy-compare";
 import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector";
+//#region src/tracking.ts
+const useStoreLayoutEffect$1 = typeof window === "undefined" ? useEffect : useLayoutEffect;
+/**
+* Subscribe through either an explicit selector, shallow snapshots, or render access tracking
+*/
+function useStoreValue(store, selector, tracking) {
+	const committedTracking = useRef(void 0);
+	const [proxyCache] = useState(() => /* @__PURE__ */ new WeakMap());
+	const [calibration, calibrate] = useReducer((previous, snapshot) => ({
+		snapshot,
+		version: (previous?.version ?? 0) + 1
+	}), void 0);
+	const selectSnapshot = useCallback((snapshot) => {
+		const currentSnapshot = calibration && Object.is(calibration.snapshot, snapshot) ? calibration.snapshot : snapshot;
+		return selector ? selector(currentSnapshot) : currentSnapshot;
+	}, [calibration, selector]);
+	const compareSelections = useCallback((previous, next) => {
+		if (selector || !tracking) return shallowEqual(previous, next);
+		const committed = committedTracking.current;
+		if (!committed) return Object.is(previous, next);
+		return !isChanged(committed.snapshot, next, committed.affected, /* @__PURE__ */ new WeakMap());
+	}, [selector, tracking]);
+	const snapshot = useSyncExternalStoreWithSelector(store.subscribe, store.getSnapshot, store.getSnapshot, selectSnapshot, compareSelections);
+	const affected = /* @__PURE__ */ new WeakMap();
+	const shouldTrack = !selector && tracking;
+	const value = shouldTrack ? createProxy(snapshot, affected, proxyCache) : snapshot;
+	useStoreLayoutEffect$1(() => {
+		if (shouldTrack) {
+			const renderedSnapshot = snapshot;
+			committedTracking.current = {
+				affected,
+				snapshot: renderedSnapshot
+			};
+			const currentSnapshot = store.getSnapshot();
+			if (isChanged(renderedSnapshot, currentSnapshot, affected, /* @__PURE__ */ new WeakMap())) calibrate(currentSnapshot);
+		}
+	}, [
+		affected,
+		shouldTrack,
+		snapshot,
+		store
+	]);
+	return value;
+}
+/**
+* Compare values by identity first and enumerable top-level fields second
+*/
+function shallowEqual(left, right) {
+	if (Object.is(left, right)) return true;
+	if (!isShallowComparable(left) || !isShallowComparable(right)) return false;
+	const leftKeys = Object.keys(left);
+	if (leftKeys.length !== Object.keys(right).length) return false;
+	return leftKeys.every((key) => Object.prototype.hasOwnProperty.call(right, key) && Object.is(left[key], right[key]));
+}
+/**
+* Narrow values before enumerable field comparison
+*/
+function isShallowComparable(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === Array.prototype;
+}
+//#endregion
 //#region src/index.tsx
 const useStoreLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 /**
-* Create a selector-first React Store and its matching Provider
+* Create a React Store with automatic tracking and explicit selector support
 */
-function createStore(useModel) {
+function createStore(useModel, options) {
 	const StoreContext = createContext(void 0);
 	const storeName = useModel.name || "KerrosStore";
+	const tracking = options?.tracking ?? true;
 	/** Run the model Hook and publish its committed snapshot */
 	const StoreProvider = (props) => {
 		const { children, ...storeProps } = props;
@@ -19,29 +84,28 @@ function createStore(useModel) {
 	StoreProvider.displayName = `${storeName}Provider`;
 	StoreContext.displayName = `${storeName}Context`;
 	/** Select Store fields through the stable Provider container */
-	const useStore = (selector) => {
-		return useStoreSelector(useStoreContext(StoreContext), selector);
-	};
+	const useStore = ((selector) => {
+		return useStoreValue(useStoreContext(StoreContext), selector, tracking);
+	});
 	return [useStore, StoreProvider];
 }
-/**
-* Bind existing external Store instances to scoped React consumers
-*/
-function bindStore(name = "KerrosExternalStore") {
+function bindStore(nameOrOptions = "KerrosExternalStore", inputOptions) {
+	const name = typeof nameOrOptions === "string" ? nameOrOptions : "KerrosExternalStore";
+	const tracking = (typeof nameOrOptions === "string" ? inputOptions : nameOrOptions)?.tracking ?? true;
 	const StoreContext = createContext(void 0);
 	/** Provide one existing Store instance without copying its snapshot */
-	const StoreProvider = (props) => {
+	const StoreProvider = ((props) => {
 		const { children, store } = props;
 		return createElement(StoreContext.Provider, { value: store }, children);
-	};
+	});
 	StoreProvider.displayName = `${name}Provider`;
 	StoreContext.displayName = `${name}Context`;
 	/** Select snapshot fields directly from the bound external Store */
-	const useStore = (selector) => {
-		return useStoreSelector(useStoreContext(StoreContext), selector);
-	};
+	const useStore = ((selector) => {
+		return useStoreValue(useStoreContext(StoreContext), selector, tracking);
+	});
 	/** Read the exact Store instance bound to the current Provider */
-	const useInstance = () => useStoreContext(StoreContext);
+	const useInstance = (() => useStoreContext(StoreContext));
 	return [
 		useStore,
 		StoreProvider,
@@ -75,20 +139,5 @@ function useStoreContext(context) {
 	if (!store) throw new Error("Kerros store hook must be used within its matching Provider");
 	return store;
 }
-/**
-* Select fields directly from an external Store subscription
-*/
-function useStoreSelector(store, selector) {
-	return useSyncExternalStoreWithSelector(store.subscribe, store.getSnapshot, store.getSnapshot, selector, shallowEqual);
-}
-/**
-* Compare selector objects by their enumerable top-level fields
-*/
-function shallowEqual(left, right) {
-	if (Object.is(left, right)) return true;
-	const leftKeys = Object.keys(left);
-	if (leftKeys.length !== Object.keys(right).length) return false;
-	return leftKeys.every((key) => Object.prototype.hasOwnProperty.call(right, key) && Object.is(left[key], right[key]));
-}
 //#endregion
 export { bindStore, createStore };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@violetflux/kerros",
-  "version": "0.1.8",
-  "description": "Hook-native state sharing for React with focused selector subscriptions.",
+  "version": "0.2.0",
+  "description": "Hook-native state sharing for React with automatic access tracking and focused selectors.",
   "keywords": [
     "react",
     "react-hooks",
@@ -26,6 +26,9 @@
   "license": "MIT",
   "author": "Violetflux",
   "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
   "sideEffects": false,
   "files": [
     "dist",
@@ -47,17 +50,27 @@
     }
   },
   "scripts": {
-    "build": "tsdown",
+    "build": "bun run build:runtime && bun run build:plugin",
+    "build:runtime": "tsdown",
+    "build:plugin": "bun run --filter @violetflux/eslint-plugin-kerros build",
+    "benchmark:eslint": "bun benchmarks/eslint/run.ts",
+    "benchmark:tracking": "bun benchmarks/tracking/runtime.tsx",
     "dev": "rspress dev",
     "docs:build": "rspress build",
     "docs:preview": "rspress preview",
     "docs:check": "bun scripts/check-docs.ts",
+    "quality:check": "bun scripts/check-selectors.ts",
     "lint": "eslint .",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "typecheck": "bun run typecheck:runtime && bun run typecheck:plugin",
+    "typecheck:runtime": "tsc --noEmit",
+    "typecheck:plugin": "bun run --filter @violetflux/eslint-plugin-kerros typecheck",
+    "test": "bun run test:runtime && bun run test:plugin",
+    "test:runtime": "vitest run",
+    "test:plugin": "bun run --filter @violetflux/eslint-plugin-kerros test",
+    "test:benchmarks": "vitest run --config benchmarks/vitest.config.ts",
     "test:watch": "vitest",
-    "check": "bun run lint && bun run typecheck && bun run test && bun run build && bun run docs:check && bun run docs:build",
-    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build"
+    "check": "bun run quality:check && bun run lint && bun run typecheck && bun run test && bun run build && bun run docs:check && bun run docs:build",
+    "prepublishOnly": "bun run quality:check && bun run lint && bun run typecheck && bun run test && bun run build"
   },
   "publishConfig": {
     "access": "public"
@@ -66,11 +79,13 @@
     "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
   },
   "dependencies": {
+    "proxy-compare": "3.0.1",
     "use-sync-external-store": "1.6.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@rspress/core": "2.0.17",
+    "@types/jsdom": "28.0.3",
     "@types/node": "26.1.1",
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
@@ -81,6 +96,7 @@
     "jsdom": "29.1.1",
     "react": "19.2.7",
     "react-dom": "19.2.7",
+    "tinybench": "6.1.2",
     "tsdown": "0.22.9",
     "typescript": "5.9.3",
     "typescript-eslint": "8.64.0",