@violetflux/kerros 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.de.md CHANGED
@@ -21,14 +21,12 @@ Kerros lässt React-State dort, wo er natürlich hingehört: in Hooks und unter
21
21
  - Stores lassen sich über einseitige Abhängigkeiten komponieren
22
22
  - Unterstützt React 17, 18 und 19
23
23
 
24
- ## Installation
24
+ > [!TIP]
25
+ > **Mit Codex installieren**: Füge diesen Satz in Codex ein, um Abhängigkeit und Projekt-Skill gemeinsam zu installieren.
25
26
 
26
- | Paketmanager | Befehl |
27
- | --- | --- |
28
- | npm | `npm install @violetflux/kerros` |
29
- | pnpm | `pnpm add @violetflux/kerros` |
30
- | Yarn | `yarn add @violetflux/kerros` |
31
- | Bun | `bun add @violetflux/kerros` |
27
+ ```text
28
+ Installiere @violetflux/kerros mit dem Paketmanager dieses Projekts und führe danach npx skills add violetflux/kerros --skill kerros --agent codex -y aus.
29
+ ```
32
30
 
33
31
  ## Store erstellen
34
32
 
@@ -62,6 +60,15 @@ function App() {
62
60
 
63
61
  Der Selektor darf inline stehen. Änderungen an nicht ausgewählten Feldern rendern `Counter` nicht neu.
64
62
 
63
+ ## Installation
64
+
65
+ | Paketmanager | Befehl |
66
+ | --- | --- |
67
+ | npm | `npm install @violetflux/kerros` |
68
+ | pnpm | `pnpm add @violetflux/kerros` |
69
+ | Yarn | `yarn add @violetflux/kerros` |
70
+ | Bun | `bun add @violetflux/kerros` |
71
+
65
72
  ## Funktionsweise
66
73
 
67
74
  Der Provider führt den Store Hook aus und gibt über Context nur einen stabilen Abonnement-Container weiter. Bestätigte Snapshots werden mit `subscribe/getSnapshot` veröffentlicht. Eine Komponente rendert nur neu, wenn sich ihre Auswahl ändert.
package/README.es.md CHANGED
@@ -21,14 +21,12 @@ Kerros mantiene el estado de React donde pertenece de forma natural: dentro de H
21
21
  - Los Stores se componen mediante dependencias unidireccionales
22
22
  - Compatible con React 17, 18 y 19
23
23
 
24
- ## Instalación
24
+ > [!TIP]
25
+ > **Instalar con Codex**: pega esta frase en Codex para instalar la dependencia y el Skill del proyecto a la vez.
25
26
 
26
- | Gestor | Comando |
27
- | --- | --- |
28
- | npm | `npm install @violetflux/kerros` |
29
- | pnpm | `pnpm add @violetflux/kerros` |
30
- | Yarn | `yarn add @violetflux/kerros` |
31
- | Bun | `bun add @violetflux/kerros` |
27
+ ```text
28
+ Instala @violetflux/kerros con el gestor de paquetes del proyecto y después ejecuta npx skills add violetflux/kerros --skill kerros --agent codex -y.
29
+ ```
32
30
 
33
31
  ## Crear un Store
34
32
 
@@ -62,6 +60,15 @@ function App() {
62
60
 
63
61
  El selector puede escribirse en línea. Cambiar un campo no seleccionado no vuelve a renderizar `Counter`.
64
62
 
63
+ ## Instalación
64
+
65
+ | Gestor | Comando |
66
+ | --- | --- |
67
+ | npm | `npm install @violetflux/kerros` |
68
+ | pnpm | `pnpm add @violetflux/kerros` |
69
+ | Yarn | `yarn add @violetflux/kerros` |
70
+ | Bun | `bun add @violetflux/kerros` |
71
+
65
72
  ## Cómo funciona
66
73
 
67
74
  El Provider ejecuta el Hook del Store y Context solo transporta un contenedor de suscripción estable. Los snapshots confirmados se publican mediante `subscribe/getSnapshot`. Cada componente se renderiza de nuevo únicamente cuando cambia su selección.
package/README.fr.md CHANGED
@@ -21,14 +21,12 @@ Kerros conserve l'état React là où il se trouve naturellement : dans les Hook
21
21
  - Les Stores se composent grâce à des dépendances unidirectionnelles
22
22
  - Compatible avec React 17, 18 et 19
23
23
 
24
- ## Installation
24
+ > [!TIP]
25
+ > **Installer avec Codex** : collez cette phrase dans Codex pour installer à la fois la dépendance et le Skill du projet.
25
26
 
26
- | Gestionnaire | Commande |
27
- | --- | --- |
28
- | npm | `npm install @violetflux/kerros` |
29
- | pnpm | `pnpm add @violetflux/kerros` |
30
- | Yarn | `yarn add @violetflux/kerros` |
31
- | Bun | `bun add @violetflux/kerros` |
27
+ ```text
28
+ Installe @violetflux/kerros avec le gestionnaire de paquets du projet, puis exécute npx skills add violetflux/kerros --skill kerros --agent codex -y.
29
+ ```
32
30
 
33
31
  ## Créer un Store
34
32
 
@@ -62,6 +60,15 @@ function App() {
62
60
 
63
61
  Le sélecteur peut rester en ligne. La modification d'un champ non sélectionné ne provoque pas un nouveau rendu de `Counter`.
64
62
 
63
+ ## Installation
64
+
65
+ | Gestionnaire | Commande |
66
+ | --- | --- |
67
+ | npm | `npm install @violetflux/kerros` |
68
+ | pnpm | `pnpm add @violetflux/kerros` |
69
+ | Yarn | `yarn add @violetflux/kerros` |
70
+ | Bun | `bun add @violetflux/kerros` |
71
+
65
72
  ## Fonctionnement
66
73
 
67
74
  Le Provider exécute le Hook du Store et Context ne transporte qu'un conteneur d'abonnement stable. Les snapshots validés sont publiés via `subscribe/getSnapshot`. Un composant n'est rendu à nouveau que lorsque sa sélection change.
package/README.ja.md CHANGED
@@ -21,14 +21,12 @@ Kerros は React の状態を Hook の中、Provider の下という自然な場
21
21
  - 一方向の依存関係で Store を合成可能
22
22
  - React 17、18、19 をサポート
23
23
 
24
- ## インストール
24
+ > [!TIP]
25
+ > **Codex でインストール**:次の一文を Codex に貼り付けると、依存関係とプロジェクト Skill をまとめてインストールできます。
25
26
 
26
- | パッケージマネージャー | コマンド |
27
- | --- | --- |
28
- | npm | `npm install @violetflux/kerros` |
29
- | pnpm | `pnpm add @violetflux/kerros` |
30
- | Yarn | `yarn add @violetflux/kerros` |
31
- | Bun | `bun add @violetflux/kerros` |
27
+ ```text
28
+ このプロジェクトのパッケージマネージャーで @violetflux/kerros をインストールし、npx skills add violetflux/kerros --skill kerros --agent codex -y を実行してください。
29
+ ```
32
30
 
33
31
  ## Store を作成する
34
32
 
@@ -63,6 +61,15 @@ function App() {
63
61
 
64
62
  selector はインラインで記述できます。選択していないフィールドの変更では `Counter` は再レンダーされません。
65
63
 
64
+ ## インストール
65
+
66
+ | パッケージマネージャー | コマンド |
67
+ | --- | --- |
68
+ | npm | `npm install @violetflux/kerros` |
69
+ | pnpm | `pnpm add @violetflux/kerros` |
70
+ | Yarn | `yarn add @violetflux/kerros` |
71
+ | Bun | `bun add @violetflux/kerros` |
72
+
66
73
  ## 仕組み
67
74
 
68
75
  Provider は Store Hook を実行し、Context には安定した購読コンテナだけを渡します。コミット済みスナップショットは `subscribe/getSnapshot` で公開され、各コンポーネントは選択結果が変わったときだけ再レンダーされます。
package/README.ko.md CHANGED
@@ -21,14 +21,12 @@ Kerros는 React 상태를 Hook 안과 Provider 아래라는 자연스러운 위
21
21
  - 단방향 의존성을 통한 Store 조합
22
22
  - React 17, 18, 19 지원
23
23
 
24
- ## 설치
24
+ > [!TIP]
25
+ > **Codex로 설치**: 아래 문장을 Codex에 붙여넣으면 의존성과 프로젝트 Skill을 함께 설치합니다.
25
26
 
26
- | 패키지 매니저 | 명령 |
27
- | --- | --- |
28
- | npm | `npm install @violetflux/kerros` |
29
- | pnpm | `pnpm add @violetflux/kerros` |
30
- | Yarn | `yarn add @violetflux/kerros` |
31
- | Bun | `bun add @violetflux/kerros` |
27
+ ```text
28
+ 현재 프로젝트의 패키지 매니저로 @violetflux/kerros를 설치한 다음 npx skills add violetflux/kerros --skill kerros --agent codex -y를 실행하세요.
29
+ ```
32
30
 
33
31
  ## Store 만들기
34
32
 
@@ -63,6 +61,15 @@ function App() {
63
61
 
64
62
  selector는 인라인으로 작성할 수 있습니다. 선택하지 않은 필드가 바뀌어도 `Counter`는 다시 렌더링되지 않습니다.
65
63
 
64
+ ## 설치
65
+
66
+ | 패키지 매니저 | 명령 |
67
+ | --- | --- |
68
+ | npm | `npm install @violetflux/kerros` |
69
+ | pnpm | `pnpm add @violetflux/kerros` |
70
+ | Yarn | `yarn add @violetflux/kerros` |
71
+ | Bun | `bun add @violetflux/kerros` |
72
+
66
73
  ## 작동 방식
67
74
 
68
75
  Provider는 Store Hook을 실행하고 Context에는 안정적인 구독 컨테이너만 전달합니다. 커밋된 스냅샷은 `subscribe/getSnapshot`으로 게시되며 컴포넌트는 선택 결과가 바뀔 때만 다시 렌더링됩니다.
package/README.md CHANGED
@@ -18,6 +18,7 @@
18
18
  <a href="https://www.npmjs.com/package/@violetflux/kerros"><img src="https://img.shields.io/npm/v/@violetflux/kerros?color=7c3aed" alt="npm version" /></a>
19
19
  <a href="https://github.com/violetflux/kerros/actions/workflows/ci.yml"><img src="https://github.com/violetflux/kerros/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
20
20
  <a href="https://bundlephobia.com/package/@violetflux/kerros"><img src="https://img.shields.io/bundlephobia/minzip/@violetflux/kerros?label=gzip&color=2563eb" alt="minified gzip size" /></a>
21
+ <a href="https://skills.sh/violetflux/kerros"><img src="https://skills.sh/b/violetflux/kerros" alt="Install Kerros Skill" /></a>
21
22
  <a href="https://github.com/violetflux/kerros/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@violetflux/kerros" alt="MIT license" /></a>
22
23
  </p>
23
24
 
@@ -25,36 +26,12 @@ Kerros is a lightweight way to share state between React components.
25
26
 
26
27
  Write a Store the same way you write a custom Hook. When local state needs to be shared, pass it to `createStore`, mount its Provider, and let each component select what it needs.
27
28
 
28
- ## Install
29
-
30
- | Package manager | Command |
31
- | --- | --- |
32
- | npm | `npm install @violetflux/kerros` |
33
- | pnpm | `pnpm add @violetflux/kerros` |
34
- | Yarn | `yarn add @violetflux/kerros` |
35
- | Bun | `bun add @violetflux/kerros` |
29
+ > [!TIP]
30
+ > **Install with Codex** — copy and paste this sentence into Codex to install both the dependency and the project Skill:
36
31
 
37
- React 17, React 18, and React 19 are supported.
38
-
39
- ## Why Kerros?
40
-
41
- - **Almost nothing new to learn** — reuse the React knowledge you already have; if you can write a custom Hook, you can write a Store
42
- - **Designed for flexible refactoring** — Stores and components use the same Hook API, so local state can become shared state with very little work
43
- - **Local and application-wide state** — Provider placement determines the Store scope, balancing flexibility with simplicity
44
- - **Avoid Context-wide rerenders** — Context carries a stable container and components rerender only when their selector result changes
45
- - **TypeScript support** — Store and selector types are inferred without duplicate declarations
46
-
47
- ## From state management to state sharing
48
-
49
- Libraries such as Redux, Zustand, and Recoil can all share data, but their central job is still to organize state, update it, and define how data flows. “State management” is the right name for them.
50
-
51
- Kerros focuses on a smaller and more direct problem. It does not invent a new data model or prescribe how async logic should work. It answers one question: **how can a piece of Hook state be shared between React components?**
52
-
53
- 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.
54
-
55
- 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.
56
-
57
- 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.
32
+ ```text
33
+ Install @violetflux/kerros with this project's package manager, then run npx skills add violetflux/kerros --skill kerros --agent codex -y.
34
+ ```
58
35
 
59
36
  ## Quick start
60
37
 
@@ -131,6 +108,37 @@ function TaskList() {
131
108
 
132
109
  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`.
133
110
 
111
+ ## Install
112
+
113
+ | Package manager | Command |
114
+ | --- | --- |
115
+ | npm | `npm install @violetflux/kerros` |
116
+ | pnpm | `pnpm add @violetflux/kerros` |
117
+ | Yarn | `yarn add @violetflux/kerros` |
118
+ | Bun | `bun add @violetflux/kerros` |
119
+
120
+ React 17, React 18, and React 19 are supported.
121
+
122
+ ## Why Kerros?
123
+
124
+ - **Almost nothing new to learn** — reuse the React knowledge you already have; if you can write a custom Hook, you can write a Store
125
+ - **Designed for flexible refactoring** — Stores and components use the same Hook API, so local state can become shared state with very little work
126
+ - **Local and application-wide state** — Provider placement determines the Store scope, balancing flexibility with simplicity
127
+ - **Avoid Context-wide rerenders** — Context carries a stable container and components rerender only when their selector result changes
128
+ - **TypeScript support** — Store and selector types are inferred without duplicate declarations
129
+
130
+ ## From state management to state sharing
131
+
132
+ Libraries such as Redux, Zustand, and Recoil can all share data, but their central job is still to organize state, update it, and define how data flows. “State management” is the right name for them.
133
+
134
+ Kerros focuses on a smaller and more direct problem. It does not invent a new data model or prescribe how async logic should work. It answers one question: **how can a piece of Hook state be shared between React components?**
135
+
136
+ 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.
137
+
138
+ 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.
139
+
140
+ 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.
141
+
134
142
  ## Multiple instances
135
143
 
136
144
  Each `TaskProvider` owns independent state:
package/README.zh-CN.md CHANGED
@@ -18,36 +18,12 @@ Kerros 是一个在 React 组件间共享状态的轻量方案。
18
18
 
19
19
  你怎么写 custom Hook,就可以怎么写 Store。只有当局部状态需要被多个组件使用时,再交给 `createStore`,用 Provider 决定共享范围,用 selector 选择组件真正需要的数据。
20
20
 
21
- ## 安装
22
-
23
- | 包管理器 | 命令 |
24
- | --- | --- |
25
- | npm | `npm install @violetflux/kerros` |
26
- | pnpm | `pnpm add @violetflux/kerros` |
27
- | Yarn | `yarn add @violetflux/kerros` |
28
- | Bun | `bun add @violetflux/kerros` |
21
+ > [!TIP]
22
+ > **使用 Codex 安装**:复制下面这句话并粘贴给 Codex,它会同时安装依赖和当前项目的 Skill:
29
23
 
30
- 支持 React 17、React 18 和 React 19。
31
-
32
- ## 为什么要用 Kerros?
33
-
34
- - **几乎没有学习成本**:直接复用已有的 React 知识,你怎么写 custom Hook,就可以怎么写 Store
35
- - **为灵活重构而设计**:Store 和组件使用同一套 Hook API,可以近乎零成本地把组件局部状态转换成组件间共享状态
36
- - **同时支持局部状态和全局状态**:Provider 决定 Store 的作用域,在灵活和简单之间取得平衡
37
- - **解决 Context 的重复渲染问题**:Context 只传递稳定容器,selector 选择结果不变的组件不会重渲染
38
- - **优秀的 TypeScript 支持**:Store 和 selector 类型自动推断,不需要重复声明
39
-
40
- ## 从状态管理到状态共享
41
-
42
- Redux、Zustand、Recoil 这些状态管理库当然也能解决数据共享问题,但它们最核心的能力仍然是组织数据、操作数据和约束数据流,因此它们应该被称为“状态管理”工具。
43
-
44
- Kerros 想解决的问题更小,也更直接。它不发明新的数据结构,不规定异步和数据流应该怎么写,只聚焦一个痛点:**如何在多个 React 组件间共享一段 Hook 状态。**
45
-
46
- 层层传递 `value`、`onChange` 会逐渐破坏组件边界;粗暴地把数据全部塞进一个全局 Store,也不会自动让应用获得更好的扩展性和可维护性。
47
-
48
- 直接用 React Context 共享变化频繁的状态也会带来重复渲染:Context value 每次变化,所有消费者都会更新。Kerros 保留 Provider 的作用域和多实例能力,但 Context 只传递稳定容器;组件通过 selector 订阅数据,只有选择结果变化时才重渲染。
49
-
50
- Kerros 简单、轻量、可靠。先把状态写成普通 Hook,需要共享时再交给 `createStore`;Provider 决定状态共享到哪里,selector 决定每个组件订阅什么。
24
+ ```text
25
+ 使用当前项目的包管理器安装 @violetflux/kerros,然后运行 npx skills add violetflux/kerros --skill kerros --agent codex -y。
26
+ ```
51
27
 
52
28
  ## 快速上手
53
29
 
@@ -124,6 +100,37 @@ function TaskList() {
124
100
 
125
101
  Kerros 会浅比较 selector 返回对象的顶层字段。只要这些选中字段保持不变,Store 的其他更新就不会让 `TaskList` 重渲染。selector 可以直接写在调用位置,不需要 `useCallback`。
126
102
 
103
+ ## 安装
104
+
105
+ | 包管理器 | 命令 |
106
+ | --- | --- |
107
+ | npm | `npm install @violetflux/kerros` |
108
+ | pnpm | `pnpm add @violetflux/kerros` |
109
+ | Yarn | `yarn add @violetflux/kerros` |
110
+ | Bun | `bun add @violetflux/kerros` |
111
+
112
+ 支持 React 17、React 18 和 React 19。
113
+
114
+ ## 为什么要用 Kerros?
115
+
116
+ - **几乎没有学习成本**:直接复用已有的 React 知识,你怎么写 custom Hook,就可以怎么写 Store
117
+ - **为灵活重构而设计**:Store 和组件使用同一套 Hook API,可以近乎零成本地把组件局部状态转换成组件间共享状态
118
+ - **同时支持局部状态和全局状态**:Provider 决定 Store 的作用域,在灵活和简单之间取得平衡
119
+ - **解决 Context 的重复渲染问题**:Context 只传递稳定容器,selector 选择结果不变的组件不会重渲染
120
+ - **优秀的 TypeScript 支持**:Store 和 selector 类型自动推断,不需要重复声明
121
+
122
+ ## 从状态管理到状态共享
123
+
124
+ Redux、Zustand、Recoil 这些状态管理库当然也能解决数据共享问题,但它们最核心的能力仍然是组织数据、操作数据和约束数据流,因此它们应该被称为“状态管理”工具。
125
+
126
+ Kerros 想解决的问题更小,也更直接。它不发明新的数据结构,不规定异步和数据流应该怎么写,只聚焦一个痛点:**如何在多个 React 组件间共享一段 Hook 状态。**
127
+
128
+ 层层传递 `value`、`onChange` 会逐渐破坏组件边界;粗暴地把数据全部塞进一个全局 Store,也不会自动让应用获得更好的扩展性和可维护性。
129
+
130
+ 直接用 React Context 共享变化频繁的状态也会带来重复渲染:Context value 每次变化,所有消费者都会更新。Kerros 保留 Provider 的作用域和多实例能力,但 Context 只传递稳定容器;组件通过 selector 订阅数据,只有选择结果变化时才重渲染。
131
+
132
+ Kerros 简单、轻量、可靠。先把状态写成普通 Hook,需要共享时再交给 `createStore`;Provider 决定状态共享到哪里,selector 决定每个组件订阅什么。
133
+
127
134
  ## 多个实例
128
135
 
129
136
  每个 `TaskProvider` 都拥有独立状态:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@violetflux/kerros",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "description": "Hook-native state sharing for React with focused selector subscriptions.",
5
5
  "keywords": [
6
6
  "react",
@@ -10,7 +10,9 @@
10
10
  "store",
11
11
  "selector",
12
12
  "external-store",
13
- "use-sync-external-store"
13
+ "use-sync-external-store",
14
+ "agent-skills",
15
+ "codex"
14
16
  ],
15
17
  "homepage": "https://violetflux.github.io/kerros/",
16
18
  "bugs": {
@@ -25,7 +27,8 @@
25
27
  "type": "module",
26
28
  "sideEffects": false,
27
29
  "files": [
28
- "dist"
30
+ "dist",
31
+ "skills"
29
32
  ],
30
33
  "main": "./dist/index.cjs",
31
34
  "module": "./dist/index.mjs",
@@ -0,0 +1,139 @@
1
+ ---
2
+ name: kerros
3
+ description: Implement, refactor, review, or test shared React state with @violetflux/kerros. Use for createStore, Provider scoping, selector subscriptions, cross-Store composition, migrating from Hox or frequently changing React Context, preventing Context-wide rerenders, and React 17–19 compatibility.
4
+ ---
5
+
6
+ # Kerros
7
+
8
+ Build shared state from ordinary React Hooks. Keep Provider scope and multiple instances while selectors prevent unrelated consumers from rerendering.
9
+
10
+ ## Workflow
11
+
12
+ 1. Inspect the project package manager, React version, existing state owner, Provider tree, and naming conventions.
13
+ 2. Keep state local when only one component needs it. Create a Kerros Store only when several components need the same Hook state.
14
+ 3. Group state by domain and identify one authoritative owner for every mutable value.
15
+ 4. Create the Store, mount its Provider at the narrowest shared ancestor, and migrate consumers to focused selectors.
16
+ 5. Order composed Providers from dependency to dependent and reject circular Store dependencies.
17
+ 6. Run the project's typecheck, tests, lint, and the narrowest useful render test.
18
+
19
+ ## Install
20
+
21
+ Use the package manager already present in the project:
22
+
23
+ ```sh
24
+ npm install @violetflux/kerros
25
+ pnpm add @violetflux/kerros
26
+ yarn add @violetflux/kerros
27
+ bun add @violetflux/kerros
28
+ ```
29
+
30
+ Kerros supports React 17, 18, and 19. Do not change package managers or create an additional lockfile.
31
+
32
+ ## Core pattern
33
+
34
+ Write the Store as an ordinary Hook directly inside `createStore`. Name the public pair after the domain; do not repeat `Store` unless the codebase already requires it.
35
+
36
+ ```tsx
37
+ import { createStore } from '@violetflux/kerros'
38
+ import { useState } from 'react'
39
+
40
+ export const [useCounter, CounterProvider] = createStore(() => {
41
+ const [count, setCount] = useState(0)
42
+ const increment = () => setCount(v => v + 1)
43
+
44
+ return { count, increment }
45
+ })
46
+ ```
47
+
48
+ Mount the Provider at the narrowest ancestor shared by all consumers:
49
+
50
+ ```tsx
51
+ function App() {
52
+ return (
53
+ <CounterProvider>
54
+ <Counter />
55
+ </CounterProvider>
56
+ )
57
+ }
58
+ ```
59
+
60
+ Select an object containing only the fields the component reads. Keep the selector inline and use `s` as its parameter:
61
+
62
+ ```tsx
63
+ function Counter() {
64
+ const { count, increment } = useCounter(s => ({
65
+ count: s.count,
66
+ increment: s.increment,
67
+ }))
68
+
69
+ return <button onClick={increment}>{count}</button>
70
+ }
71
+ ```
72
+
73
+ Kerros shallowly compares the selected object's top-level fields with `Object.is`. An update to an unselected field must not rerender this component.
74
+
75
+ ## Provider props
76
+
77
+ Accept initialization or scope-specific inputs as Store Hook props. Pass them to the generated Provider instead of reading mutable module globals.
78
+
79
+ ```tsx
80
+ const [useGreeting, GreetingProvider] = createStore((props: { initialName: string }) => {
81
+ const [name, setName] = useState(props.initialName)
82
+ return { name, setName }
83
+ })
84
+
85
+ <GreetingProvider initialName="Ada">
86
+ <Profile />
87
+ </GreetingProvider>
88
+ ```
89
+
90
+ ## Compose Stores
91
+
92
+ An inner Store may call an outer Store Hook. Mount the dependency first and keep the graph one-way.
93
+
94
+ ```tsx
95
+ const [useSession, SessionProvider] = createStore(() => {
96
+ const [userId, setUserId] = useState<string>()
97
+ return { userId, setUserId }
98
+ })
99
+
100
+ const [usePermissions, PermissionsProvider] = createStore(() => {
101
+ const { userId } = useSession(s => ({ userId: s.userId }))
102
+ return { canEdit: Boolean(userId) }
103
+ })
104
+
105
+ function Providers({ children }: PropsWithChildren) {
106
+ return (
107
+ <SessionProvider>
108
+ <PermissionsProvider>{children}</PermissionsProvider>
109
+ </SessionProvider>
110
+ )
111
+ }
112
+ ```
113
+
114
+ ## Guardrails
115
+
116
+ - Require every Store read to use an object selector. Do not use array selectors.
117
+ - Select concrete fields and actions. Do not expose or select a changing aggregate Store snapshot.
118
+ - Do not wrap inline selectors with `useCallback`; Kerros handles selector identity.
119
+ - Keep public actions as ordinary functions. In React 19, use `useEffectEvent` only for events called from Effects, never as a public Store action.
120
+ - Do not mirror the same mutable state across Stores. Read it from its authoritative Store or move ownership.
121
+ - Do not create circular Store dependencies. Split ownership or invert the Provider order.
122
+ - Do not call a Store Hook outside its matching Provider; Kerros intentionally throws a clear error.
123
+ - Do not replace scoped Providers with a hidden module singleton. Put an application-wide Provider at the root only when the state is truly application-wide.
124
+ - Preserve SDK caches, subscriptions, and streams under a single owning Store when duplicating the Hook would duplicate external work.
125
+ - Respect the project's React version. Avoid React 19-only APIs when the consuming project still supports React 17 or 18.
126
+
127
+ ## Migrate existing state
128
+
129
+ - From React Context: keep the Provider boundary, move the changing value into `createStore`, and replace broad `useContext` reads with focused selectors.
130
+ - From Hox: replace the factory with `createStore`, add the explicit Provider, remove compatibility exports, and migrate every consumer to an object selector.
131
+ - From a global Store: split by domain only when ownership and dependencies stay clear; do not split merely by field count.
132
+
133
+ ## Verify
134
+
135
+ - Confirm all consumers are below the correct Provider and multiple Provider instances stay isolated.
136
+ - Test Provider props, Strict Mode, subscription cleanup, and the outside-Provider error when changing Store infrastructure.
137
+ - Add a render-count test showing that changing an unselected field does not rerender the consumer.
138
+ - Search for broad Store selections, array selectors, duplicate subscriptions, and dependency cycles.
139
+ - Run the consuming project's existing validation commands without introducing a new package manager.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Kerros"
3
+ short_description: "Build selector-based shared React state with Kerros"
4
+ default_prompt: "Use $kerros to implement shared React state with createStore, Providers, and focused selectors."