@violetflux/kerros 0.1.4 → 0.1.6

package/README.de.md

@@ -21,6 +21,13 @@ Kerros lässt React-State dort, wo er natürlich hingehört: in Hooks und unter
 - Stores lassen sich über einseitige Abhängigkeiten komponieren
 - Unterstützt React 17, 18 und 19
 
+> [!TIP]
+> **Mit Codex installieren**: Füge diesen Satz in Codex ein, um Abhängigkeit und Projekt-Skill gemeinsam zu installieren.
+
+```text
+Installiere @violetflux/kerros mit dem Paketmanager dieses Projekts und führe danach npx skills add violetflux/kerros --skill kerros --agent codex -y aus.
+```
+
 ## Store erstellen
 
 ```tsx

package/README.es.md

@@ -21,6 +21,13 @@ Kerros mantiene el estado de React donde pertenece de forma natural: dentro de H
 - Los Stores se componen mediante dependencias unidireccionales
 - Compatible con React 17, 18 y 19
 
+> [!TIP]
+> **Instalar con Codex**: pega esta frase en Codex para instalar la dependencia y el Skill del proyecto a la vez.
+
+```text
+Instala @violetflux/kerros con el gestor de paquetes del proyecto y después ejecuta npx skills add violetflux/kerros --skill kerros --agent codex -y.
+```
+
 ## Crear un Store
 
 ```tsx

package/README.fr.md

@@ -21,6 +21,13 @@ Kerros conserve l'état React là où il se trouve naturellement : dans les Hook
 - Les Stores se composent grâce à des dépendances unidirectionnelles
 - Compatible avec React 17, 18 et 19
 
+> [!TIP]
+> **Installer avec Codex** : collez cette phrase dans Codex pour installer à la fois la dépendance et le Skill du projet.
+
+```text
+Installe @violetflux/kerros avec le gestionnaire de paquets du projet, puis exécute npx skills add violetflux/kerros --skill kerros --agent codex -y.
+```
+
 ## Créer un Store
 
 ```tsx

package/README.ja.md

@@ -21,6 +21,13 @@ Kerros は React の状態を Hook の中、Provider の下という自然な場
 - 一方向の依存関係で Store を合成可能
 - React 17、18、19 をサポート
 
+> [!TIP]
+> **Codex でインストール**：次の一文を Codex に貼り付けると、依存関係とプロジェクト Skill をまとめてインストールできます。
+
+```text
+このプロジェクトのパッケージマネージャーで @violetflux/kerros をインストールし、npx skills add violetflux/kerros --skill kerros --agent codex -y を実行してください。
+```
+
 ## Store を作成する
 
 ```tsx

package/README.ko.md

@@ -21,6 +21,13 @@ Kerros는 React 상태를 Hook 안과 Provider 아래라는 자연스러운 위
 - 단방향 의존성을 통한 Store 조합
 - React 17, 18, 19 지원
 
+> [!TIP]
+> **Codex로 설치**: 아래 문장을 Codex에 붙여넣으면 의존성과 프로젝트 Skill을 함께 설치합니다.
+
+```text
+현재 프로젝트의 패키지 매니저로 @violetflux/kerros를 설치한 다음 npx skills add violetflux/kerros --skill kerros --agent codex -y를 실행하세요.
+```
+
 ## Store 만들기
 
 ```tsx

package/README.md

@@ -18,6 +18,7 @@
   <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>
   <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>
   <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>
+  <a href="https://github.com/violetflux/kerros/tree/main/skills/kerros"><img src="https://img.shields.io/badge/Agent_Skill-Kerros-7c3aed" alt="Kerros Agent Skill" /></a>
   <a href="https://github.com/violetflux/kerros/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@violetflux/kerros" alt="MIT license" /></a>
 </p>
 
@@ -25,6 +26,13 @@ Kerros is a lightweight way to share state between React components.
 
 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.
 
+> [!TIP]
+> **Install with Codex** — copy and paste this sentence into Codex to install both the dependency and the project Skill:
+
+```text
+Install @violetflux/kerros with this project's package manager, then run npx skills add violetflux/kerros --skill kerros --agent codex -y.
+```
+
 ## Quick start
 
 ### Create a Store

package/README.zh-CN.md

@@ -18,6 +18,13 @@ Kerros 是一个在 React 组件间共享状态的轻量方案。
 
 你怎么写 custom Hook，就可以怎么写 Store。只有当局部状态需要被多个组件使用时，再交给 `createStore`，用 Provider 决定共享范围，用 selector 选择组件真正需要的数据。
 
+> [!TIP]
+> **使用 Codex 安装**：复制下面这句话并粘贴给 Codex，它会同时安装依赖和当前项目的 Skill：
+
+```text
+使用当前项目的包管理器安装 @violetflux/kerros，然后运行 npx skills add violetflux/kerros --skill kerros --agent codex -y。
+```
+
 ## 快速上手
 
 ### 创建 Store

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@violetflux/kerros",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Hook-native state sharing for React with focused selector subscriptions.",
   "keywords": [
     "react",
@@ -10,7 +10,9 @@
     "store",
     "selector",
     "external-store",
-    "use-sync-external-store"
+    "use-sync-external-store",
+    "agent-skills",
+    "codex"
   ],
   "homepage": "https://violetflux.github.io/kerros/",
   "bugs": {
@@ -25,7 +27,8 @@
   "type": "module",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",

package/skills/kerros/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: kerros
+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.
+---
+
+# Kerros
+
+Build shared state from ordinary React Hooks. Keep Provider scope and multiple instances while selectors prevent unrelated consumers from rerendering.
+
+## Workflow
+
+1. Inspect the project package manager, React version, existing state owner, Provider tree, and naming conventions.
+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. Create the Store, mount its Provider at the narrowest shared ancestor, and migrate consumers to focused selectors.
+5. Order composed Providers from dependency to dependent and reject circular Store dependencies.
+6. Run the project's typecheck, tests, lint, and the narrowest useful render test.
+
+## Install
+
+Use the package manager already present in the project:
+
+```sh
+npm install @violetflux/kerros
+pnpm add @violetflux/kerros
+yarn add @violetflux/kerros
+bun add @violetflux/kerros
+```
+
+Kerros supports React 17, 18, and 19. Do not change package managers or create an additional lockfile.
+
+## Core pattern
+
+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.
+
+```tsx
+import { createStore } from '@violetflux/kerros'
+import { useState } from 'react'
+
+export const [useCounter, CounterProvider] = createStore(() => {
+  const [count, setCount] = useState(0)
+  const increment = () => setCount(v => v + 1)
+
+  return { count, increment }
+})
+```
+
+Mount the Provider at the narrowest ancestor shared by all consumers:
+
+```tsx
+function App() {
+  return (
+    <CounterProvider>
+      <Counter />
+    </CounterProvider>
+  )
+}
+```
+
+Select an object containing only the fields the component reads. Keep the selector inline and use `s` as its parameter:
+
+```tsx
+function Counter() {
+  const { count, increment } = useCounter(s => ({
+    count: s.count,
+    increment: s.increment,
+  }))
+
+  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.
+
+## Provider props
+
+Accept initialization or scope-specific inputs as Store Hook props. Pass them to the generated Provider instead of reading mutable module globals.
+
+```tsx
+const [useGreeting, GreetingProvider] = createStore((props: { initialName: string }) => {
+  const [name, setName] = useState(props.initialName)
+  return { name, setName }
+})
+
+<GreetingProvider initialName="Ada">
+  <Profile />
+</GreetingProvider>
+```
+
+## Compose Stores
+
+An inner Store may call an outer Store Hook. Mount the dependency first and keep the graph one-way.
+
+```tsx
+const [useSession, SessionProvider] = createStore(() => {
+  const [userId, setUserId] = useState<string>()
+  return { userId, setUserId }
+})
+
+const [usePermissions, PermissionsProvider] = createStore(() => {
+  const { userId } = useSession(s => ({ userId: s.userId }))
+  return { canEdit: Boolean(userId) }
+})
+
+function Providers({ children }: PropsWithChildren) {
+  return (
+    <SessionProvider>
+      <PermissionsProvider>{children}</PermissionsProvider>
+    </SessionProvider>
+  )
+}
+```
+
+## Guardrails
+
+- 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.
+- Do not wrap inline selectors with `useCallback`; Kerros handles selector identity.
+- Keep public actions as ordinary functions. 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.
+- Do not create circular Store dependencies. Split ownership or invert the Provider order.
+- Do not call a Store Hook outside its matching Provider; Kerros intentionally throws a clear error.
+- 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.
+- Preserve SDK caches, subscriptions, and streams under a single owning Store when duplicating the Hook would duplicate external work.
+- Respect the project's React version. Avoid React 19-only APIs when the consuming project still supports React 17 or 18.
+
+## 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 a global Store: split by domain only when ownership and dependencies stay clear; do not split merely by field count.
+
+## Verify
+
+- Confirm all consumers are below the correct Provider and multiple Provider instances stay isolated.
+- 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.
+- Run the consuming project's existing validation commands without introducing a new package manager.

package/skills/kerros/agents/openai.yaml

@@ -0,0 +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, Providers, and focused selectors."