@violetflux/kerros 0.1.7 → 0.1.9

package/README.de.md

@@ -34,14 +34,18 @@ Installiere @violetflux/kerros mit dem Paketmanager dieses Projekts und führe d
 import { createStore } from '@violetflux/kerros'
 import { useState } from 'react'
 
-export const [useCounter, CounterProvider] = createStore(() => {
+function useCounterModel() {
   const [count, setCount] = useState(0)
   return { count, setCount }
-})
+}
+
+export const [useCounter, CounterProvider] = createStore(useCounterModel)
 ```
 
 Im Store Hook können weiterhin `useState`, `useReducer`, Context, SDK Hooks und eigene Hooks verwendet werden.
 
+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
 
 ```tsx
@@ -79,12 +83,16 @@ Ohne verstecktes Modul-Singleton kann derselbe Provider mehrfach eingebunden, ü
 
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
-  useStoreValue: (props: TProps) => TStore,
+  useModel: (props: TProps) => TStore,
 ): readonly [StoreHook<TStore>, StoreProvider<TProps>]
+
+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.
 
+`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.
+
 ## Dokumentation
 
 - [Einführung](https://violetflux.github.io/kerros/de/guide/introduction)

package/README.es.md

@@ -34,14 +34,18 @@ Instala @violetflux/kerros con el gestor de paquetes del proyecto y después eje
 import { createStore } from '@violetflux/kerros'
 import { useState } from 'react'
 
-export const [useCounter, CounterProvider] = createStore(() => {
+function useCounterModel() {
   const [count, setCount] = useState(0)
   return { count, setCount }
-})
+}
+
+export const [useCounter, CounterProvider] = createStore(useCounterModel)
 ```
 
 El Hook del Store puede seguir usando `useState`, `useReducer`, Context, Hooks de SDK y Hooks personalizados.
 
+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
 
 ```tsx
@@ -79,12 +83,16 @@ Sin un singleton de módulo oculto, el mismo Provider puede montarse varias vece
 
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
-  useStoreValue: (props: TProps) => TStore,
+  useModel: (props: TProps) => TStore,
 ): readonly [StoreHook<TStore>, StoreProvider<TProps>]
+
+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.
 
+`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`.
+
 ## Documentación
 
 - [Introducción](https://violetflux.github.io/kerros/es/guide/introduction)

package/README.fr.md

@@ -34,14 +34,18 @@ Installe @violetflux/kerros avec le gestionnaire de paquets du projet, puis exé
 import { createStore } from '@violetflux/kerros'
 import { useState } from 'react'
 
-export const [useCounter, CounterProvider] = createStore(() => {
+function useCounterModel() {
   const [count, setCount] = useState(0)
   return { count, setCount }
-})
+}
+
+export const [useCounter, CounterProvider] = createStore(useCounterModel)
 ```
 
 Le Hook du Store peut continuer à utiliser `useState`, `useReducer`, Context, des Hooks SDK et vos Hooks personnalisés.
 
+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
 
 ```tsx
@@ -79,12 +83,16 @@ Sans singleton de module caché, un même Provider peut être monté plusieurs f
 
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
-  useStoreValue: (props: TProps) => TStore,
+  useModel: (props: TProps) => TStore,
 ): readonly [StoreHook<TStore>, StoreProvider<TProps>]
+
+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.
 
+`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`.
+
 ## Documentation
 
 - [Introduction](https://violetflux.github.io/kerros/fr/guide/introduction)

package/README.ja.md

@@ -34,14 +34,18 @@ Kerros は React の状態を Hook の中、Provider の下という自然な場
 import { createStore } from '@violetflux/kerros'
 import { useState } from 'react'
 
-export const [useCounter, CounterProvider] = createStore(() => {
+function useCounterModel() {
   const [count, setCount] = useState(0)
   return { count, setCount }
-})
+}
+
+export const [useCounter, CounterProvider] = createStore(useCounterModel)
 ```
 
 Store Hook 内では `useState`、`useReducer`、Context、SDK Hook、カスタム Hook をそのまま利用できます。
 
+initializer は `useCounterModel` のようなモジュール直下の名前付き Hook として定義してください。匿名 initializer も実行時には動作しますが、React Compiler の `infer` モードでは Hook として自動コンパイルされません。
+
 ## Provider を配置して値を選択する
 
 ```tsx
@@ -80,12 +84,16 @@ Provider は Store Hook を実行し、Context には安定した購読コンテ
 
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
-  useStoreValue: (props: TProps) => TStore,
+  useModel: (props: TProps) => TStore,
 ): readonly [StoreHook<TStore>, StoreProvider<TProps>]
+
+const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 ```
 
 返される Store Hook にはオブジェクトを返す selector が必須です。対応する Provider の外で呼び出すと明確なエラーを送出します。Strict Mode とサーバーレンダリングをサポートします。
 
+高度な連携として、既存の Headless External Store にだけ `bindStore` を使います。通常の Hook 状態には `createStore` を使ってください。Context は元の Store インスタンスだけを保持し、コンシューマーは `getSnapshot` と `subscribe` を直接利用します。
+
 ## ドキュメント
 
 - [はじめに](https://violetflux.github.io/kerros/ja/guide/introduction)

package/README.ko.md

@@ -34,14 +34,18 @@ Kerros는 React 상태를 Hook 안과 Provider 아래라는 자연스러운 위
 import { createStore } from '@violetflux/kerros'
 import { useState } from 'react'
 
-export const [useCounter, CounterProvider] = createStore(() => {
+function useCounterModel() {
   const [count, setCount] = useState(0)
   return { count, setCount }
-})
+}
+
+export const [useCounter, CounterProvider] = createStore(useCounterModel)
 ```
 
 Store Hook 안에서 `useState`, `useReducer`, Context, SDK Hook, 사용자 Hook을 그대로 사용할 수 있습니다.
 
+initializer는 `useCounterModel`처럼 모듈 최상위의 이름 있는 Hook으로 정의하세요. 익명 initializer도 런타임에서는 동작하지만 React Compiler의 `infer` 모드에서는 Hook으로 자동 컴파일되지 않습니다.
+
 ## Provider를 마운트하고 필요한 값 선택하기
 
 ```tsx
@@ -80,12 +84,16 @@ Provider는 Store Hook을 실행하고 Context에는 안정적인 구독 컨테
 
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
-  useStoreValue: (props: TProps) => TStore,
+  useModel: (props: TProps) => TStore,
 ): readonly [StoreHook<TStore>, StoreProvider<TProps>]
+
+const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 ```
 
 반환된 Store Hook에는 객체를 반환하는 selector가 필요합니다. 대응하는 Provider 밖에서 호출하면 명확한 오류가 발생합니다. Strict Mode와 서버 렌더링을 지원합니다.
 
+고급 통합이 필요한 기존 Headless External Store에만 `bindStore`를 사용하세요. 일반 Hook 상태에는 `createStore`를 사용합니다. Context는 원래 Store 인스턴스만 보관하고 소비자는 `getSnapshot`과 `subscribe`를 직접 사용합니다.
+
 ## 문서
 
 - [소개](https://violetflux.github.io/kerros/ko/guide/introduction)

package/README.md

@@ -48,7 +48,7 @@ interface Task {
   title: string
 }
 
-export const [useTask, TaskProvider] = createStore(() => {
+function useTaskModel() {
   const [tasks, setTasks] = useState<Task[]>([])
 
   const addTask = (task: Task) => {
@@ -60,13 +60,17 @@ export const [useTask, TaskProvider] = createStore(() => {
   }
 
   return { tasks, addTask, finishTask }
-})
+}
+
+export const [useTask, TaskProvider] = createStore(useTaskModel)
 ```
 
 `createStore` returns two values: the Hook used by components and its matching Provider.
 
 The Store is still a normal React Hook. It may use `useState`, `useReducer`, Context, SDK Hooks, or your own custom Hooks.
 
+Keep the initializer as a top-level named Hook such as `useTaskModel`. Anonymous initializers still work at runtime, but React Compiler `infer` mode does not automatically compile them as Hooks.
+
 ### Mount the Provider
 
 Only descendants of `TaskProvider` may use `useTask`:
@@ -162,7 +166,7 @@ Each `TaskList` automatically reads its nearest Provider.
 A Store may call another Store directly. For example, a task Store can read the current account:
 
 ```tsx
-export const [useTask, TaskProvider] = createStore(() => {
+function useTaskModel() {
   const { user } = useAccount(s => ({ user: s.user }))
   const [tasks, setTasks] = useState<Task[]>([])
 
@@ -178,7 +182,9 @@ export const [useTask, TaskProvider] = createStore(() => {
   }
 
   return { tasks, addTask }
-})
+}
+
+export const [useTask, TaskProvider] = createStore(useTaskModel)
 ```
 
 Mount Providers in dependency order and keep dependencies one-way:
@@ -200,12 +206,12 @@ interface CounterProps {
   initialCount: number
 }
 
-const [useCounter, CounterProvider] = createStore(
-  ({ initialCount }: CounterProps) => {
-    const [count, setCount] = useState(initialCount)
-    return { count, setCount }
-  },
-)
+function useCounterModel({ initialCount }: CounterProps) {
+  const [count, setCount] = useState(initialCount)
+  return { count, setCount }
+}
+
+const [useCounter, CounterProvider] = createStore(useCounterModel)
 ```
 
 ```tsx
@@ -216,18 +222,40 @@ const [useCounter, CounterProvider] = createStore(
 
 ## API
 
+### `createStore` (default)
+
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
-  useStoreValue: (props: TProps) => TStore,
+  useModel: (props: TProps) => TStore,
 ): readonly [StoreHook<TStore>, StoreProvider<TProps>]
 ```
 
-- `useStoreValue` follows the Rules of Hooks
-- Provider props, excluding `children`, are passed to `useStoreValue`
+- `useModel` follows the Rules of Hooks
+- Provider props, excluding `children`, are passed to `useModel`
 - the returned Store Hook requires 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
 
+### Advanced: bind an existing external Store
+
+Most applications only need `createStore`. Use `bindStore` when a library or SDK already owns authoritative state outside React and exposes stable `getSnapshot` and `subscribe` functions.
+
+Without this API, an integration must either repeat the Context and selector subscription code or copy the external snapshot through a second Store. `bindStore` provides Provider scoping and selectors while keeping the original Store as the only state owner.
+
+```tsx
+const [useStream, StreamBindingProvider] = bindStore<Stream>('Stream')
+
+<StreamBindingProvider store={stream}>
+  <App />
+</StreamBindingProvider>
+```
+
+The Provider stores only the original Store instance in Context. Consumers subscribe directly, so Kerros does not copy snapshots or add another publication layer. The component that creates the Store keeps lifecycle and imperative access.
+
+In one sentence: `bindStore` is a React adapter for an external Store, not a state synchronizer. State remains only in the original Store; React reads it with `getSnapshot` after a subscription notification.
+
+If the state begins in `useState`, `useReducer`, an SDK Hook, or another custom Hook, keep using `createStore`.
+
 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.
 
 ## Documentation

package/README.zh-CN.md

@@ -40,7 +40,7 @@ interface Task {
   title: string
 }
 
-export const [useTask, TaskProvider] = createStore(() => {
+function useTaskModel() {
   const [tasks, setTasks] = useState<Task[]>([])
 
   const addTask = (task: Task) => {
@@ -52,13 +52,17 @@ export const [useTask, TaskProvider] = createStore(() => {
   }
 
   return { tasks, addTask, finishTask }
-})
+}
+
+export const [useTask, TaskProvider] = createStore(useTaskModel)
 ```
 
 `createStore` 返回两个值：组件调用的 Hook 和对应的 Provider。
 
 Store 仍然是普通 React Hook，可以继续使用 `useState`、`useReducer`、Context、SDK Hook 或其他 custom Hook。
 
+请把 initializer 写成 `useTaskModel` 这类同文件顶层命名 Hook。匿名 initializer 在运行时仍然可用，但 React Compiler 的 `infer` 模式不会自动把它识别并编译为 Hook。
+
 ### 挂载 Provider
 
 只有 `TaskProvider` 的子节点可以调用 `useTask`：
@@ -154,7 +158,7 @@ Kerros 简单、轻量、可靠。先把状态写成普通 Hook，需要共享
 一个 Store 可以直接调用另一个 Store。例如任务 Store 读取当前账户：
 
 ```tsx
-export const [useTask, TaskProvider] = createStore(() => {
+function useTaskModel() {
   const { user } = useAccount(s => ({ user: s.user }))
   const [tasks, setTasks] = useState<Task[]>([])
 
@@ -170,7 +174,9 @@ export const [useTask, TaskProvider] = createStore(() => {
   }
 
   return { tasks, addTask }
-})
+}
+
+export const [useTask, TaskProvider] = createStore(useTaskModel)
 ```
 
 按依赖顺序挂 Provider，并保持单向依赖：
@@ -192,12 +198,12 @@ interface CounterProps {
   initialCount: number
 }
 
-const [useCounter, CounterProvider] = createStore(
-  ({ initialCount }: CounterProps) => {
-    const [count, setCount] = useState(initialCount)
-    return { count, setCount }
-  },
-)
+function useCounterModel({ initialCount }: CounterProps) {
+  const [count, setCount] = useState(initialCount)
+  return { count, setCount }
+}
+
+const [useCounter, CounterProvider] = createStore(useCounterModel)
 ```
 
 ```tsx
@@ -208,18 +214,40 @@ const [useCounter, CounterProvider] = createStore(
 
 ## API
 
+### `createStore`（默认用法）
+
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
-  useStoreValue: (props: TProps) => TStore,
+  useModel: (props: TProps) => TStore,
 ): readonly [StoreHook<TStore>, StoreProvider<TProps>]
 ```
 
-- `useStoreValue` 必须遵守 Hooks 规则
-- 除 `children` 外的 Provider props 会传给 `useStoreValue`
+- `useModel` 必须遵守 Hooks 规则
+- 除 `children` 外的 Provider props 会传给 `useModel`
 - Store Hook 必须接收一个返回对象的 selector
 - 在对应 Provider 外调用会抛出明确错误
 - 支持 Strict Mode、服务端渲染和 Provider 多实例
 
+### 高级用法：绑定已有 External Store
+
+绝大多数应用只需要 `createStore`。只有当某个库或 SDK 已经在 React 外持有权威状态，并提供稳定的 `getSnapshot` 和 `subscribe` 函数时，才使用 `bindStore`。
+
+没有这个 API 时，集成层只能重复实现 Context 和 selector 订阅，或者把 External Store 快照复制进第二个 Store。`bindStore` 只提供 Provider 作用域和 selector，原 Store 仍是唯一状态所有者。
+
+```tsx
+const [useStream, StreamBindingProvider] = bindStore<Stream>('Stream')
+
+<StreamBindingProvider store={stream}>
+  <App />
+</StreamBindingProvider>
+```
+
+Provider 的 Context 只保存原 Store 实例，组件直接订阅它；Kerros 不复制快照，也不增加中间发布层。创建 Store 的组件继续负责生命周期和命令式访问。
+
+一句话理解：`bindStore` 是 External Store 的 React 适配器，不是状态同步器。状态仍只存在于原 Store 中，React 在收到订阅通知后通过 `getSnapshot` 读取它。
+
+如果状态来自 `useState`、`useReducer`、SDK Hook 或其他 custom Hook，继续使用 `createStore`。
+
 React 17 使用官方 `use-sync-external-store` shim；React 18 和 19 可用时优先使用 React 原生实现。React Compiler 不是必需项。
 
 ## 文档

package/dist/index.cjs

@@ -6,28 +6,50 @@ const useStoreLayoutEffect = typeof window === "undefined" ? react.useEffect : r
 /**
 * Create a selector-first React Store and its matching Provider
 */
-function createStore(useStoreValue) {
+function createStore(useModel) {
 	const StoreContext = (0, react.createContext)(void 0);
-	const storeName = useStoreValue.name || "KerrosStore";
-	/** Run the Store hook and publish its committed snapshot */
+	const storeName = useModel.name || "KerrosStore";
+	/** Run the model Hook and publish its committed snapshot */
 	const StoreProvider = (props) => {
 		const { children, ...storeProps } = props;
-		const value = useStoreValue(storeProps);
-		const [container] = (0, react.useState)(() => createStoreContainer(value));
-		useStoreLayoutEffect(() => container.publish(value), [container, value]);
+		const model = useModel(storeProps);
+		const [container] = (0, react.useState)(() => createStoreContainer(model));
+		useStoreLayoutEffect(() => container.publish(model), [container, model]);
 		return (0, react.createElement)(StoreContext.Provider, { value: container }, children);
 	};
 	StoreProvider.displayName = `${storeName}Provider`;
 	StoreContext.displayName = `${storeName}Context`;
 	/** Select Store fields through the stable Provider container */
 	const useStore = (selector) => {
-		const container = (0, react.useContext)(StoreContext);
-		if (!container) throw new Error("Kerros store hook must be used within its matching Provider");
-		return (0, use_sync_external_store_shim_with_selector.useSyncExternalStoreWithSelector)(container.subscribe, container.getSnapshot, container.getSnapshot, selector, shallowEqual);
+		return useStoreSelector(useStoreContext(StoreContext), selector);
 	};
 	return [useStore, StoreProvider];
 }
 /**
+* Bind existing external Store instances to scoped React consumers
+*/
+function bindStore(name = "KerrosExternalStore") {
+	const StoreContext = (0, react.createContext)(void 0);
+	/** Provide one existing Store instance without copying its snapshot */
+	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);
+	};
+	/** Read the exact Store instance bound to the current Provider */
+	const useInstance = () => useStoreContext(StoreContext);
+	return [
+		useStore,
+		StoreProvider,
+		useInstance
+	];
+}
+/**
 * Create the stable external-store container for one Provider instance
 */
 function createStoreContainer(initialSnapshot) {
@@ -47,6 +69,20 @@ function createStoreContainer(initialSnapshot) {
 	};
 }
 /**
+* Read the Store bound to the current Provider
+*/
+function useStoreContext(context) {
+	const store = (0, react.useContext)(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) {
@@ -56,4 +92,5 @@ function shallowEqual(left, right) {
 	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

@@ -8,9 +8,26 @@ interface StoreHook<TStore> {
 }
 /** Provider created for a Store hook */
 type StoreProvider<TProps> = FC<PropsWithChildren<TProps>>;
+/** Existing external Store contract supported by bindStore */
+interface ExternalStore<TSnapshot> {
+  /** Read the current immutable snapshot */
+  getSnapshot: () => TSnapshot;
+  /** Subscribe to snapshot changes */
+  subscribe: (listener: () => void) => () => void;
+}
+/** 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];
 /**
  * Create a selector-first React Store and its matching Provider
  */
-declare function createStore<TStore, TProps = Record<never, never>>(useStoreValue: (props: TProps) => TStore): readonly [StoreHook<TStore>, StoreProvider<TProps>];
+declare function createStore<TStore, TProps = Record<never, never>>(useModel: (props: TProps) => TStore): 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>;
 //#endregion
-export { StoreHook, StoreProvider, StoreSelector, createStore };
+export { ExternalStore, ExternalStoreSnapshot, StoreBinding, StoreHook, StoreProvider, StoreSelector, bindStore, createStore };

package/dist/index.d.mts

@@ -8,9 +8,26 @@ interface StoreHook<TStore> {
 }
 /** Provider created for a Store hook */
 type StoreProvider<TProps> = FC<PropsWithChildren<TProps>>;
+/** Existing external Store contract supported by bindStore */
+interface ExternalStore<TSnapshot> {
+  /** Read the current immutable snapshot */
+  getSnapshot: () => TSnapshot;
+  /** Subscribe to snapshot changes */
+  subscribe: (listener: () => void) => () => void;
+}
+/** 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];
 /**
  * Create a selector-first React Store and its matching Provider
  */
-declare function createStore<TStore, TProps = Record<never, never>>(useStoreValue: (props: TProps) => TStore): readonly [StoreHook<TStore>, StoreProvider<TProps>];
+declare function createStore<TStore, TProps = Record<never, never>>(useModel: (props: TProps) => TStore): 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>;
 //#endregion
-export { StoreHook, StoreProvider, StoreSelector, createStore };
+export { ExternalStore, ExternalStoreSnapshot, StoreBinding, StoreHook, StoreProvider, StoreSelector, bindStore, createStore };

package/dist/index.mjs

@@ -5,28 +5,50 @@ const useStoreLayoutEffect = typeof window === "undefined" ? useEffect : useLayo
 /**
 * Create a selector-first React Store and its matching Provider
 */
-function createStore(useStoreValue) {
+function createStore(useModel) {
 	const StoreContext = createContext(void 0);
-	const storeName = useStoreValue.name || "KerrosStore";
-	/** Run the Store hook and publish its committed snapshot */
+	const storeName = useModel.name || "KerrosStore";
+	/** Run the model Hook and publish its committed snapshot */
 	const StoreProvider = (props) => {
 		const { children, ...storeProps } = props;
-		const value = useStoreValue(storeProps);
-		const [container] = useState(() => createStoreContainer(value));
-		useStoreLayoutEffect(() => container.publish(value), [container, value]);
+		const model = useModel(storeProps);
+		const [container] = useState(() => createStoreContainer(model));
+		useStoreLayoutEffect(() => container.publish(model), [container, model]);
 		return createElement(StoreContext.Provider, { value: container }, children);
 	};
 	StoreProvider.displayName = `${storeName}Provider`;
 	StoreContext.displayName = `${storeName}Context`;
 	/** Select Store fields through the stable Provider container */
 	const useStore = (selector) => {
-		const container = useContext(StoreContext);
-		if (!container) throw new Error("Kerros store hook must be used within its matching Provider");
-		return useSyncExternalStoreWithSelector(container.subscribe, container.getSnapshot, container.getSnapshot, selector, shallowEqual);
+		return useStoreSelector(useStoreContext(StoreContext), selector);
 	};
 	return [useStore, StoreProvider];
 }
 /**
+* Bind existing external Store instances to scoped React consumers
+*/
+function bindStore(name = "KerrosExternalStore") {
+	const StoreContext = createContext(void 0);
+	/** Provide one existing Store instance without copying its snapshot */
+	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);
+	};
+	/** Read the exact Store instance bound to the current Provider */
+	const useInstance = () => useStoreContext(StoreContext);
+	return [
+		useStore,
+		StoreProvider,
+		useInstance
+	];
+}
+/**
 * Create the stable external-store container for one Provider instance
 */
 function createStoreContainer(initialSnapshot) {
@@ -46,6 +68,20 @@ function createStoreContainer(initialSnapshot) {
 	};
 }
 /**
+* Read the Store bound to the current Provider
+*/
+function useStoreContext(context) {
+	const store = useContext(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) {
@@ -55,4 +91,4 @@ function shallowEqual(left, right) {
 	return leftKeys.every((key) => Object.prototype.hasOwnProperty.call(right, key) && Object.is(left[key], right[key]));
 }
 //#endregion
-export { createStore };
+export { bindStore, createStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@violetflux/kerros",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Hook-native state sharing for React with focused selector subscriptions.",
   "keywords": [
     "react",

package/skills/kerros/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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.
 ---
 
 # Kerros
@@ -12,9 +12,10 @@ Build shared state from ordinary React Hooks. Keep Provider scope and multiple i
 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.
+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.
+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.
 
 ## Install
 
@@ -31,18 +32,20 @@ Kerros supports React 17, 18, and 19. Do not change package managers or create a
 
 ## 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.
+Define the Store implementation as a top-level named Hook ending in `Model`, then pass that function to `createStore`. The model may return both state and actions. 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(() => {
+function useCounterModel() {
   const [count, setCount] = useState(0)
   const increment = () => setCount(v => v + 1)
 
   return { count, increment }
-})
+}
+
+export const [useCounter, CounterProvider] = createStore(useCounterModel)
 ```
 
 Mount the Provider at the narrowest ancestor shared by all consumers:
@@ -72,15 +75,53 @@ function Counter() {
 
 Kerros shallowly compares the selected object's top-level fields with `Object.is`. An update to an unselected field must not rerender this component.
 
+## Advanced external Store binding
+
+Most applications should stop at `createStore`. Use `bindStore` only when a headless Store already owns authoritative state outside React and exposes stable `getSnapshot` and `subscribe` functions.
+
+```tsx
+import { bindStore } from '@violetflux/kerros'
+
+export const [
+  useStream,
+  StreamBindingProvider,
+  useStreamInstance,
+] = bindStore<Stream>('Stream')
+```
+
+Mount the original instance without mirroring its snapshot:
+
+```tsx
+<StreamBindingProvider store={stream}>
+  <App />
+</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.
+
+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.
+
+Do not replace this with `createStore(() => useSyncExternalStore(...))`; that subscribes the Provider to the entire external snapshot and republishes it through a second container.
+
+## React Compiler and identity
+
+- 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.
+- 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
 
 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 }) => {
+function useGreetingModel(props: { initialName: string }) {
   const [name, setName] = useState(props.initialName)
   return { name, setName }
-})
+}
+
+const [useGreeting, GreetingProvider] = createStore(useGreetingModel)
 
 <GreetingProvider initialName="Ada">
   <Profile />
@@ -92,15 +133,19 @@ const [useGreeting, GreetingProvider] = createStore((props: { initialName: strin
 An inner Store may call an outer Store Hook. Mount the dependency first and keep the graph one-way.
 
 ```tsx
-const [useSession, SessionProvider] = createStore(() => {
+function useSessionModel() {
   const [userId, setUserId] = useState<string>()
   return { userId, setUserId }
-})
+}
+
+const [useSession, SessionProvider] = createStore(useSessionModel)
 
-const [usePermissions, PermissionsProvider] = createStore(() => {
+function usePermissionsModel() {
   const { userId } = useSession(s => ({ userId: s.userId }))
   return { canEdit: Boolean(userId) }
-})
+}
+
+const [usePermissions, PermissionsProvider] = createStore(usePermissionsModel)
 
 function Providers({ children }: PropsWithChildren) {
   return (
@@ -113,15 +158,16 @@ 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.
 - 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.
+- 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.
 - 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.
+- Preserve SDK caches, subscriptions, and streams under a single owner. Bind an existing headless Store directly; call a connection-owning SDK Hook inside one `createStore` initializer only when no external Store instance exists.
 - Respect the project's React version. Avoid React 19-only APIs when the consuming project still supports React 17 or 18.
 
 ## Migrate existing state
@@ -133,6 +179,7 @@ function Providers({ children }: PropsWithChildren) {
 ## Verify
 
 - 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.

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, Providers, and focused selectors."
+  default_prompt: "Use $kerros to implement shared React state with createStore or bindStore, scoped Providers, and focused selectors."