@violetflux/kerros 0.1.9 → 0.2.1

package/README.de.md

@@ -12,11 +12,11 @@
   <a href="https://github.com/violetflux/kerros/blob/main/README.es.md">Español</a>
 </p>
 
-Kerros lässt React-State dort, wo er natürlich hingehört: in Hooks und unter Providern. Die Bibliothek ergänzt gezielte Selector-Abonnements, ohne Reducer, Actions, Proxies oder globale Singletons vorzuschreiben.
+Kerros lässt React-State dort, wo er natürlich hingehört: in Hooks und unter Providern. Automatisches Property-Tracking verhindert standardmäßig unnötige Renders; explizite Selektoren bleiben für abgeleitete Werte und Hotspots verfügbar.
 
 - Ein Store ist ein normaler React Hook
-- Selektoren geben ein Objekt mit den benötigten Werten zurück
-- Oberste Felder werden flach mit `Object.is` verglichen
+- `useStore()` verfolgt gelesene Properties automatisch
+- Explizite Selektoren sind eine fortgeschrittene Optimierung
 - Jeder Provider besitzt eine isolierte Store-Instanz
 - Stores lassen sich über einseitige Abhängigkeiten komponieren
 - Unterstützt React 17, 18 und 19
@@ -46,14 +46,11 @@ Im Store Hook können weiterhin `useState`, `useReducer`, Context, SDK Hooks und
 
 Definiere den Initializer als benannten Hook auf Modulebene, zum Beispiel `useCounterModel`. Anonyme Initializer funktionieren weiterhin zur Laufzeit, werden vom React Compiler im `infer`-Modus aber nicht automatisch als Hooks kompiliert.
 
-## Provider einbinden und Werte auswählen
+## Provider einbinden und Werte lesen
 
 ```tsx
 function Counter() {
-  const { count, setCount } = useCounter(s => ({
-    count: s.count,
-    setCount: s.setCount,
-  }))
+  const { count, setCount } = useCounter()
   return <button onClick={() => setCount(count + 1)}>{count}</button>
 }
 
@@ -62,7 +59,7 @@ function App() {
 }
 ```
 
-Der Selektor darf inline stehen. Änderungen an nicht ausgewählten Feldern rendern `Counter` nicht neu.
+Kerros verfolgt die beim Rendern gelesenen Properties. Änderungen an ungelesenen Feldern rendern `Counter` nicht neu; ein Deep-Vergleich des gesamten Stores findet nicht statt.
 
 ## Installation
 
@@ -89,7 +86,7 @@ function createStore<TStore, TProps = Record<never, never>>(
 const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 ```
 
-Der zurückgegebene Store Hook verlangt einen Selektor, der ein Objekt liefert. Außerhalb des passenden Providers wird ein verständlicher Fehler ausgelöst. Strict Mode und Server Rendering werden unterstützt.
+Der zurückgegebene Store Hook verwendet ohne Argument automatisches Tracking. Explizite Objekt-Selektoren sind für abgeleitete Werte und gemessene Hotspots verfügbar. Außerhalb des passenden Providers wird ein verständlicher Fehler ausgelöst.
 
 `bindStore` ist eine fortgeschrittene Integration ausschließlich für einen bestehenden Headless External Store. Für normalen Hook-Zustand bleibt `createStore` die richtige Wahl. Der Context enthält nur die ursprüngliche Store-Instanz; Verbraucher verwenden `getSnapshot` und `subscribe` direkt.
 

package/README.es.md

@@ -12,11 +12,11 @@
   Español
 </p>
 
-Kerros mantiene el estado de React donde pertenece de forma natural: dentro de Hooks y bajo Providers. Añade suscripciones precisas mediante selectores sin imponer reducers, actions, proxies ni un singleton global.
+Kerros mantiene el estado de React donde pertenece: dentro de Hooks y bajo Providers. El seguimiento automático de propiedades evita renderizados innecesarios por defecto; los selectores explícitos siguen disponibles para valores derivados y puntos críticos.
 
 - Un Store es un Hook de React normal
-- Los selectores devuelven un objeto con los valores necesarios
-- Los campos superiores se comparan superficialmente con `Object.is`
+- `useStore()` sigue automáticamente las propiedades leídas
+- Los selectores explícitos son una optimización avanzada
 - Cada Provider posee una instancia de Store aislada
 - Los Stores se componen mediante dependencias unidireccionales
 - Compatible con React 17, 18 y 19
@@ -46,14 +46,11 @@ El Hook del Store puede seguir usando `useState`, `useReducer`, Context, Hooks d
 
 Define el initializer como un Hook con nombre en el nivel superior, por ejemplo `useCounterModel`. Los initializers anónimos siguen funcionando en runtime, pero React Compiler no los compila automáticamente como Hooks en modo `infer`.
 
-## Montar el Provider y seleccionar valores
+## Montar el Provider y leer valores
 
 ```tsx
 function Counter() {
-  const { count, setCount } = useCounter(s => ({
-    count: s.count,
-    setCount: s.setCount,
-  }))
+  const { count, setCount } = useCounter()
   return <button onClick={() => setCount(count + 1)}>{count}</button>
 }
 
@@ -62,7 +59,7 @@ function App() {
 }
 ```
 
-El selector puede escribirse en línea. Cambiar un campo no seleccionado no vuelve a renderizar `Counter`.
+Kerros sigue las propiedades leídas durante el renderizado. Cambiar un campo no leído no vuelve a renderizar `Counter`, sin comparar profundamente todo el Store.
 
 ## Instalación
 
@@ -89,7 +86,7 @@ function createStore<TStore, TProps = Record<never, never>>(
 const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 ```
 
-El Hook devuelto requiere un selector que retorne un objeto. Usarlo fuera de su Provider correspondiente produce un error claro. Admite Strict Mode y renderizado en servidor.
+Sin argumentos, el Hook devuelto usa seguimiento automático. Los selectores de objeto explícitos quedan para valores derivados y puntos críticos medidos. Usarlo fuera de su Provider produce un error claro.
 
 `bindStore` es una integración avanzada solo para un Headless External Store existente. Para el estado normal de Hooks, usa `createStore`. El Context solo contiene la instancia original; los consumidores utilizan directamente `getSnapshot` y `subscribe`.
 

package/README.fr.md

@@ -12,11 +12,11 @@
   <a href="https://github.com/violetflux/kerros/blob/main/README.es.md">Español</a>
 </p>
 
-Kerros conserve l'état React là où il se trouve naturellement : dans les Hooks et sous les Providers. Il ajoute des abonnements précis par sélecteur sans imposer reducers, actions, proxies ou singleton global.
+Kerros conserve l'état React là où il se trouve naturellement : dans les Hooks et sous les Providers. Le suivi automatique des propriétés évite par défaut les rendus inutiles ; les sélecteurs explicites restent disponibles pour les valeurs dérivées et les points chauds.
 
 - Un Store est un Hook React ordinaire
-- Les sélecteurs renvoient un objet contenant les valeurs nécessaires
-- Les champs de premier niveau sont comparés avec `Object.is`
+- `useStore()` suit automatiquement les propriétés lues
+- Les sélecteurs explicites sont une optimisation avancée
 - Chaque Provider possède une instance de Store isolée
 - Les Stores se composent grâce à des dépendances unidirectionnelles
 - Compatible avec React 17, 18 et 19
@@ -46,14 +46,11 @@ Le Hook du Store peut continuer à utiliser `useState`, `useReducer`, Context, d
 
 Définissez l'initializer comme un Hook nommé au niveau du module, par exemple `useCounterModel`. Les initializers anonymes fonctionnent toujours à l'exécution, mais React Compiler ne les compile pas automatiquement comme Hooks en mode `infer`.
 
-## Monter le Provider et sélectionner les valeurs
+## Monter le Provider et lire les valeurs
 
 ```tsx
 function Counter() {
-  const { count, setCount } = useCounter(s => ({
-    count: s.count,
-    setCount: s.setCount,
-  }))
+  const { count, setCount } = useCounter()
   return <button onClick={() => setCount(count + 1)}>{count}</button>
 }
 
@@ -62,7 +59,7 @@ function App() {
 }
 ```
 
-Le sélecteur peut rester en ligne. La modification d'un champ non sélectionné ne provoque pas un nouveau rendu de `Counter`.
+Kerros suit les propriétés lues pendant le rendu. La modification d'un champ non lu ne provoque pas un nouveau rendu de `Counter`, sans comparaison profonde du Store complet.
 
 ## Installation
 
@@ -89,7 +86,7 @@ function createStore<TStore, TProps = Record<never, never>>(
 const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 ```
 
-Le Hook retourné exige un sélecteur qui renvoie un objet. Son utilisation hors du Provider correspondant lève une erreur claire. Strict Mode et le rendu serveur sont pris en charge.
+Sans argument, le Hook retourné active le suivi automatique. Les sélecteurs d'objet explicites servent aux valeurs dérivées et aux points chauds mesurés. Son utilisation hors du Provider lève une erreur claire.
 
 `bindStore` est une intégration avancée réservée à un Headless External Store existant. Pour un état Hook ordinaire, utilisez `createStore`. Le Context ne contient que l'instance d'origine ; les consommateurs utilisent directement `getSnapshot` et `subscribe`.
 

package/README.ja.md

@@ -12,11 +12,11 @@
   <a href="https://github.com/violetflux/kerros/blob/main/README.es.md">Español</a>
 </p>
 
-Kerros は React の状態を Hook の中、Provider の下という自然な場所に保ちます。reducer、action、proxy、グローバル singleton を導入せず、selector による限定的な購読を追加します。
+Kerros は React の状態を Hook の中、Provider の下という自然な場所に保ちます。デフォルトの自動プロパティ追跡が不要な再レンダーを防ぎ、明示的 selector は派生値や計測済みホットスポットで利用できます。
 
 - Store は通常の React Hook
-- selector は必要な値だけをオブジェクトで返す
-- 選択したトップレベルフィールドを `Object.is` で浅く比較
+- `useStore()` は読み取ったプロパティを自動追跡
+- 明示的 selector は高度な最適化として利用
 - Provider ごとに独立した Store インスタンス
 - 一方向の依存関係で Store を合成可能
 - React 17、18、19 をサポート
@@ -46,14 +46,11 @@ Store Hook 内では `useState`、`useReducer`、Context、SDK Hook、カスタ
 
 initializer は `useCounterModel` のようなモジュール直下の名前付き Hook として定義してください。匿名 initializer も実行時には動作しますが、React Compiler の `infer` モードでは Hook として自動コンパイルされません。
 
-## Provider を配置して値を選択する
+## Provider を配置して値を読み取る
 
 ```tsx
 function Counter() {
-  const { count, setCount } = useCounter(s => ({
-    count: s.count,
-    setCount: s.setCount,
-  }))
+  const { count, setCount } = useCounter()
 
   return <button onClick={() => setCount(count + 1)}>{count}</button>
 }
@@ -63,7 +60,7 @@ function App() {
 }
 ```
 
-selector はインラインで記述できます。選択していないフィールドの変更では `Counter` は再レンダーされません。
+Kerros はレンダー中に読み取ったプロパティを追跡します。未読フィールドの変更では `Counter` は再レンダーされず、Store 全体の深い比較も行いません。
 
 ## インストール
 
@@ -90,7 +87,7 @@ function createStore<TStore, TProps = Record<never, never>>(
 const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 ```
 
-返される Store Hook にはオブジェクトを返す selector が必須です。対応する Provider の外で呼び出すと明確なエラーを送出します。Strict Mode とサーバーレンダリングをサポートします。
+返される Store Hook は引数なしで自動追跡を使います。明示的なオブジェクト selector は派生値や計測済みホットスポット向けです。対応する Provider の外では明確なエラーを送出します。
 
 高度な連携として、既存の Headless External Store にだけ `bindStore` を使います。通常の Hook 状態には `createStore` を使ってください。Context は元の Store インスタンスだけを保持し、コンシューマーは `getSnapshot` と `subscribe` を直接利用します。
 

package/README.ko.md

@@ -12,11 +12,11 @@
   <a href="https://github.com/violetflux/kerros/blob/main/README.es.md">Español</a>
 </p>
 
-Kerros는 React 상태를 Hook 안과 Provider 아래라는 자연스러운 위치에 둡니다. reducer, action, proxy, 전역 singleton을 도입하지 않고 selector 기반의 정밀 구독을 제공합니다.
+Kerros는 React 상태를 Hook 안과 Provider 아래라는 자연스러운 위치에 둡니다. 기본 자동 속성 추적이 불필요한 렌더링을 막고, 명시적 selector는 파생 값과 측정된 핫스팟에 사용할 수 있습니다.
 
 - Store는 평범한 React Hook
-- selector는 필요한 값만 객체로 반환
-- 선택 객체의 최상위 필드를 `Object.is`로 얕게 비교
+- `useStore()`는 읽은 속성을 자동으로 추적
+- 명시적 selector는 고급 최적화에 사용
 - Provider마다 격리된 Store 인스턴스
 - 단방향 의존성을 통한 Store 조합
 - React 17, 18, 19 지원
@@ -46,14 +46,11 @@ Store Hook 안에서 `useState`, `useReducer`, Context, SDK Hook, 사용자 Hook
 
 initializer는 `useCounterModel`처럼 모듈 최상위의 이름 있는 Hook으로 정의하세요. 익명 initializer도 런타임에서는 동작하지만 React Compiler의 `infer` 모드에서는 Hook으로 자동 컴파일되지 않습니다.
 
-## Provider를 마운트하고 필요한 값 선택하기
+## Provider를 마운트하고 값 읽기
 
 ```tsx
 function Counter() {
-  const { count, setCount } = useCounter(s => ({
-    count: s.count,
-    setCount: s.setCount,
-  }))
+  const { count, setCount } = useCounter()
 
   return <button onClick={() => setCount(count + 1)}>{count}</button>
 }
@@ -63,7 +60,7 @@ function App() {
 }
 ```
 
-selector는 인라인으로 작성할 수 있습니다. 선택하지 않은 필드가 바뀌어도 `Counter`는 다시 렌더링되지 않습니다.
+Kerros는 렌더링 중 읽은 속성을 추적합니다. 읽지 않은 필드가 바뀌어도 `Counter`는 다시 렌더링되지 않으며 전체 Store를 깊게 비교하지 않습니다.
 
 ## 설치
 
@@ -90,7 +87,7 @@ function createStore<TStore, TProps = Record<never, never>>(
 const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 ```
 
-반환된 Store Hook에는 객체를 반환하는 selector가 필요합니다. 대응하는 Provider 밖에서 호출하면 명확한 오류가 발생합니다. Strict Mode와 서버 렌더링을 지원합니다.
+반환된 Store Hook은 인자 없이 자동 추적을 사용합니다. 명시적 객체 selector는 파생 값과 측정된 핫스팟을 위한 고급 경로입니다. Provider 밖에서 호출하면 명확한 오류가 발생합니다.
 
 고급 통합이 필요한 기존 Headless External Store에만 `bindStore`를 사용하세요. 일반 Hook 상태에는 `createStore`를 사용합니다. Context는 원래 Store 인스턴스만 보관하고 소비자는 `getSnapshot`과 `subscribe`를 직접 사용합니다.
 

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
@@ -139,9 +136,25 @@ Kerros focuses on a smaller and more direct problem. It does not invent a new da
 
 Passing `value` and `onChange` through layer after layer damages component boundaries. Moving everything into one global Store does not automatically make an application scalable or maintainable either.
 
-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.
+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. Automatic tracking observes render-time reads, so unrelated Store updates do not rerender a component.
 
-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 类型自动推断，不需要重复声明
 
 ## 从状态管理到状态共享
@@ -131,9 +128,25 @@ Kerros 想解决的问题更小，也更直接。它不发明新的数据结构
 
 层层传递 `value`、`onChange` 会逐渐破坏组件边界；粗暴地把数据全部塞进一个全局 Store，也不会自动让应用获得更好的扩展性和可维护性。
 
-直接用 React Context 共享变化频繁的状态也会带来重复渲染：Context value 每次变化，所有消费者都会更新。Kerros 保留 Provider 的作用域和多实例能力，但 Context 只传递稳定容器；组件通过 selector 订阅数据，只有选择结果变化时才重渲染。
+直接用 React Context 共享变化频繁的状态也会带来重复渲染：Context value 每次变化，所有消费者都会更新。Kerros 保留 Provider 的作用域和多实例能力，但 Context 只传递稳定容器；自动追踪根据渲染期间的读取建立订阅，无关 Store 更新不会触发组件重渲染。
 
-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.9",
-  "description": "Hook-native state sharing for React with focused selector subscriptions.",
+  "version": "0.2.1",
+  "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",

package/skills/kerros/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: kerros
-description: Implement, refactor, review, or test shared React state with @violetflux/kerros. Use for createStore, bindStore, Provider scoping, selector subscriptions, existing headless external Stores, cross-Store composition, migrating from Hox or frequently changing React Context, preventing Context-wide rerenders, and React 17–19 compatibility.
+description: Use when implementing, refactoring, reviewing, or testing shared React state with @violetflux/kerros, including createStore, bindStore, automatic property tracking, Provider scoping, explicit selectors, external Stores, cross-Store composition, Hox or Context migrations, and React 17–19 compatibility.
 ---
 
 # Kerros
 
-Build shared state from ordinary React Hooks. Keep Provider scope and multiple instances while selectors prevent unrelated consumers from rerendering.
+Build shared state from ordinary React Hooks. Keep Provider scope and multiple instances while automatic property tracking prevents unrelated consumers from rerendering by default.
 
 ## Workflow
 
@@ -13,7 +13,7 @@ Build shared state from ordinary React Hooks. Keep Provider scope and multiple i
 2. Keep state local when only one component needs it. Create a Kerros Store only when several components need the same Hook state.
 3. Group state by domain and identify one authoritative owner for every mutable value.
 4. Use `createStore` by default. Use the advanced `bindStore` API only when an authoritative headless external Store already exists.
-5. Mount the Provider at the narrowest shared ancestor and migrate consumers to focused selectors.
+5. Mount the Provider at the narrowest shared ancestor and let consumers immediately destructure the fields they read.
 6. Order composed Providers from dependency to dependent and reject circular Store dependencies.
 7. Run the project's typecheck, tests, lint, and the narrowest useful render test.
 
@@ -60,20 +60,24 @@ function App() {
 }
 ```
 
-Select an object containing only the fields the component reads. Keep the selector inline and use `s` as its parameter:
+Call the Store Hook without a selector and immediately destructure the fields used by the component:
 
 ```tsx
 function Counter() {
-  const { count, increment } = useCounter(s => ({
-    count: s.count,
-    increment: s.increment,
-  }))
+  const { count, increment } = useCounter()
 
   return <button onClick={increment}>{count}</button>
 }
 ```
 
-Kerros shallowly compares the selected object's top-level fields with `Object.is`. An update to an unselected field must not rerender this component.
+Kerros automatically tracks object, array, and nested property reads made during render. An update to an unread field must not rerender this component; Kerros does not deep-compare the complete Store.
+
+## Subscription modes
+
+- `useStore()` is the default. Read properties immediately, normally through destructuring. Do not save, return, spread, serialize, or pass the complete tracked result.
+- `useStore(s => ({ ... }))` is the advanced path for derived values or measured hot spots. Keep the selector inline, name its parameter `s`, and return an object whose top-level fields are shallowly compared with `Object.is`.
+- `createStore(model, { tracking: false })` and `bindStore({ tracking: false })` disable automatic tracking for selector-free calls and compare the complete Store at the top level instead.
+- Primitive Store snapshots use `Object.is`. `Map`, `Set`, class instances, and other atomic objects are tracked by reference as a whole.
 
 ## Advanced external Store binding
 
@@ -97,7 +101,7 @@ Mount the original instance without mirroring its snapshot:
 </StreamBindingProvider>
 ```
 
-Use `useStream` with focused selectors for snapshot reads. Use `useStreamInstance()` only in Provider descendants that need imperative commands or must supply the current instance to another headless service. It reads Context without subscribing to snapshots, so never use `useStreamInstance().getSnapshot()` for rendered state.
+Use `useStream()` with immediate property access for ordinary snapshot reads; use an explicit selector only for derived values or measured hot spots. Use `useStreamInstance()` only in Provider descendants that need imperative commands or must supply the current instance to another headless service. It reads Context without subscribing to snapshots, so never use `useStreamInstance().getSnapshot()` for rendered state.
 
 Keep creation, start, stop, and disposal in the owner that creates the instance. If that owner already has the instance, use it directly instead of calling the instance Hook.
 
@@ -108,7 +112,7 @@ Do not replace this with `createStore(() => useSyncExternalStore(...))`; that su
 - Generate `useXxxModel` as a top-level function by default. Anonymous initializers remain valid at runtime, but React Compiler `infer` mode does not automatically recognize and compile them as Hooks.
 - Let the Store producer own action identity. React Compiler may stabilize ordinary returned actions; without Compiler support, use `useCallback` only when a consumer or effect requires a stable action reference.
 - Do not claim that Kerros or `use-context-selector` can determine whether two newly allocated functions are semantically equivalent. Both can compare references, not function behavior.
-- Prefer Kerros's existing object selector behavior for consumers that return fresh objects. Kerros shallowly compares the selected object's top-level fields; `use-context-selector` applies `Object.is` to the selector result, so a newly allocated object is different.
+- For explicit selectors, Kerros shallowly compares the selected object's top-level fields; `use-context-selector` applies `Object.is` to the selector result, so a newly allocated object is different.
 - Do not recommend migrating to `use-context-selector` merely to avoid Context-wide rerenders. Kerros already keeps a stable Context container and publishes committed snapshots through `useSyncExternalStoreWithSelector`.
 
 ## Provider props
@@ -141,7 +145,7 @@ function useSessionModel() {
 const [useSession, SessionProvider] = createStore(useSessionModel)
 
 function usePermissionsModel() {
-  const { userId } = useSession(s => ({ userId: s.userId }))
+  const { userId } = useSession()
   return { canEdit: Boolean(userId) }
 }
 
@@ -159,8 +163,8 @@ function Providers({ children }: PropsWithChildren) {
 ## Guardrails
 
 - Use `createStore` for state owned by a React Hook. Treat `bindStore` as an advanced adapter for an already-authoritative headless Store; do not mirror that snapshot through another Hook Store.
-- Require every Store read to use an object selector. Do not use array selectors.
-- Select concrete fields and actions. Do not expose or select a changing aggregate Store snapshot.
+- Prefer selector-free reads with immediate destructuring. Do not let the tracked result escape render through saving, returning, spreading, serializing, or passing it as an argument.
+- When an explicit selector is justified, return an object of concrete fields and actions. Do not use array selectors or select the complete Store.
 - Do not wrap inline selectors with `useCallback`; Kerros handles selector identity.
 - Keep public actions as ordinary functions unless their reference stability is an explicit producer-side requirement. In React 19, use `useEffectEvent` only for events called from Effects, never as a public Store action.
 - Do not mirror the same mutable state across Stores. Read it from its authoritative Store or move ownership.
@@ -172,8 +176,8 @@ function Providers({ children }: PropsWithChildren) {
 
 ## Migrate existing state
 
-- From React Context: keep the Provider boundary, move the changing value into `createStore`, and replace broad `useContext` reads with focused selectors.
-- From Hox: replace the factory with `createStore`, add the explicit Provider, remove compatibility exports, and migrate every consumer to an object selector.
+- From React Context: keep the Provider boundary, move the changing value into `createStore`, and replace broad `useContext` reads with selector-free tracked access.
+- From Hox: replace the factory with `createStore`, add the explicit Provider, remove compatibility exports, and migrate consumers to immediate selector-free access.
 - From a global Store: split by domain only when ownership and dependencies stay clear; do not split merely by field count.
 
 ## Verify
@@ -181,6 +185,6 @@ function Providers({ children }: PropsWithChildren) {
 - Confirm all consumers are below the correct Provider and multiple Provider instances stay isolated.
 - Search Kerros `createStore` calls and confirm every initializer references a top-level `useXxxModel` function. Search `bindStore` calls and confirm the supplied Store owns a stable immutable snapshot.
 - Test Provider props, Strict Mode, subscription cleanup, and the outside-Provider error when changing Store infrastructure.
-- Add a render-count test showing that changing an unselected field does not rerender the consumer.
-- Search for broad Store selections, array selectors, duplicate subscriptions, and dependency cycles.
+- Add a render-count test showing that changing an unread field does not rerender the consumer.
+- Search for tracked-result escape, broad Store reads, whole-Store or array selectors, duplicate subscriptions, and dependency cycles.
 - Run the consuming project's existing validation commands without introducing a new package manager.

package/skills/kerros/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Kerros"
-  short_description: "Build selector-based shared React state with Kerros"
-  default_prompt: "Use $kerros to implement shared React state with createStore or bindStore, scoped Providers, and focused selectors."
+  short_description: "Build automatically tracked shared React state with Kerros"
+  default_prompt: "Use $kerros to implement shared React state with createStore or bindStore, scoped Providers, and selector-free automatic property tracking by default."