@violetflux/kerros 0.2.4 → 0.3.0

package/README.de.md

@@ -81,13 +81,15 @@ Ohne verstecktes Modul-Singleton kann derselbe Provider mehrfach eingebunden, ü
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
   useModel: (props: TProps) => TStore,
-): readonly [StoreHook<TStore>, StoreProvider<TProps>]
+): readonly [StoreHook<TStore>, StoreProvider<TProps>, StoreGetter<TStore>]
 
 const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 ```
 
 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.
 
+Der dritte Getter liest außerhalb von React den zuletzt committeten Provider. Mit `scope?: string | number | symbol` am Provider wählt er die neueste exakt passende Instanz. Er abonniert keine Updates und wirft ohne verfügbaren Provider einen Fehler.
+
 React-Elemente und Portale sind automatisch atomar. `useRef()` und `createRef()` können direkt zurückgegeben werden; `ref(value)` ist nur für Proxy-inkompatible Werte oder strikte Identität gedacht.
 
 `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

@@ -81,13 +81,15 @@ Sin un singleton de módulo oculto, el mismo Provider puede montarse varias vece
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
   useModel: (props: TProps) => TStore,
-): readonly [StoreHook<TStore>, StoreProvider<TProps>]
+): readonly [StoreHook<TStore>, StoreProvider<TProps>, StoreGetter<TStore>]
 
 const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 ```
 
 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.
 
+El tercer getter lee fuera de React el último Provider confirmado. Con `scope?: string | number | symbol` en el Provider selecciona la instancia más reciente que coincida exactamente. No se suscribe y lanza un error si no hay un Provider disponible.
+
 Los elementos y portales de React son atómicos automáticamente. `useRef()` y `createRef()` se pueden devolver directamente; `ref(value)` se reserva para valores incompatibles con Proxy o identidad estricta.
 
 `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

@@ -81,13 +81,15 @@ Sans singleton de module caché, un même Provider peut être monté plusieurs f
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
   useModel: (props: TProps) => TStore,
-): readonly [StoreHook<TStore>, StoreProvider<TProps>]
+): readonly [StoreHook<TStore>, StoreProvider<TProps>, StoreGetter<TStore>]
 
 const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 ```
 
 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.
 
+Le troisième getter lit hors de React le dernier Provider validé par un commit. Avec `scope?: string | number | symbol` sur le Provider, il choisit la dernière instance qui correspond exactement. Il ne s'abonne pas et lève une erreur sans Provider disponible.
+
 Les éléments et portails React sont automatiquement atomiques. `useRef()` et `createRef()` peuvent être retournés directement ; `ref(value)` est réservé aux valeurs incompatibles avec Proxy ou à l'identité stricte.
 
 `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

@@ -82,13 +82,15 @@ Provider は Store Hook を実行し、Context には安定した購読コンテ
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
   useModel: (props: TProps) => TStore,
-): readonly [StoreHook<TStore>, StoreProvider<TProps>]
+): readonly [StoreHook<TStore>, StoreProvider<TProps>, StoreGetter<TStore>]
 
 const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 ```
 
 返される Store Hook は引数なしで自動追跡を使います。明示的なオブジェクト selector は派生値や計測済みホットスポット向けです。対応する Provider の外では明確なエラーを送出します。
 
+3 番目の getter は React 外から最後にコミットされた Provider を読み取ります。Provider の `scope?: string | number | symbol` を渡すと完全一致する最新インスタンスを選べます。getter は購読せず、利用可能な Provider がなければエラーを投げます。
+
 React Element と Portal は自動的に原子的な値になります。`useRef()` と `createRef()` はそのまま返せます。`ref(value)` は Proxy 非互換の値や厳密な同一性が必要な場合だけ使います。
 
 高度な連携として、既存の Headless External Store にだけ `bindStore` を使います。通常の Hook 状態には `createStore` を使ってください。Context は元の Store インスタンスだけを保持し、コンシューマーは `getSnapshot` と `subscribe` を直接利用します。

package/README.ko.md

@@ -82,13 +82,15 @@ Provider는 Store Hook을 실행하고 Context에는 안정적인 구독 컨테
 ```ts
 function createStore<TStore, TProps = Record<never, never>>(
   useModel: (props: TProps) => TStore,
-): readonly [StoreHook<TStore>, StoreProvider<TProps>]
+): readonly [StoreHook<TStore>, StoreProvider<TProps>, StoreGetter<TStore>]
 
 const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 ```
 
 반환된 Store Hook은 인자 없이 자동 추적을 사용합니다. 명시적 객체 selector는 파생 값과 측정된 핫스팟을 위한 고급 경로입니다. Provider 밖에서 호출하면 명확한 오류가 발생합니다.
 
+세 번째 getter는 React 밖에서 마지막으로 커밋된 Provider를 읽습니다. Provider의 `scope?: string | number | symbol`을 전달하면 정확히 일치하는 최신 인스턴스를 선택합니다. getter는 구독하지 않으며 사용 가능한 Provider가 없으면 오류를 던집니다.
+
 React Element와 Portal은 자동으로 원자 값이 됩니다. `useRef()`와 `createRef()`는 그대로 반환할 수 있으며 `ref(value)`는 Proxy 비호환 값이나 엄격한 동일성이 필요할 때만 사용합니다.
 
 고급 통합이 필요한 기존 Headless External Store에만 `bindStore`를 사용하세요. 일반 Hook 상태에는 `createStore`를 사용합니다. Context는 원래 Store 인스턴스만 보관하고 소비자는 `getSnapshot`과 `subscribe`를 직접 사용합니다.

package/README.md

@@ -62,10 +62,10 @@ function useTaskModel() {
   return { tasks, addTask, finishTask }
 }
 
-export const [useTask, TaskProvider] = createStore(useTaskModel)
+export const [useTask, TaskProvider, getTask] = createStore(useTaskModel)
 ```
 
-`createStore` returns two values: the Hook used by components and its matching Provider.
+`createStore` returns the component Hook, its matching Provider, and an imperative getter for committed instances outside React.
 
 The Store is still a normal React Hook. It may use `useState`, `useReducer`, Context, SDK Hooks, or your own custom Hooks.
 
@@ -243,12 +243,14 @@ const [useCounter, CounterProvider] = createStore(useCounterModel)
 function createStore<TStore, TProps = Record<never, never>>(
   useModel: (props: TProps) => TStore,
   options?: { tracking?: boolean },
-): readonly [StoreHook<TStore>, StoreProvider<TProps>]
+): readonly [StoreHook<TStore>, StoreProvider<TProps>, StoreGetter<TStore>]
 ```
 
 - `useModel` follows the Rules of Hooks
 - Provider props, excluding `children`, are passed to `useModel`
+- Providers accept an optional `scope?: string | number | symbol` for imperative lookup
 - the returned Store Hook accepts either no argument for automatic tracking or an object-returning selector
+- the returned getter reads the latest mounted committed Provider, or the latest exact scope match; it does not subscribe
 - using the Store Hook outside its matching Provider throws a clear error
 - Provider instances work with Strict Mode and server rendering
 

package/README.zh-CN.md

@@ -54,10 +54,10 @@ function useTaskModel() {
   return { tasks, addTask, finishTask }
 }
 
-export const [useTask, TaskProvider] = createStore(useTaskModel)
+export const [useTask, TaskProvider, getTask] = createStore(useTaskModel)
 ```
 
-`createStore` 返回两个值：组件调用的 Hook 和对应的 Provider。
+`createStore` 返回组件 Hook、对应的 Provider，以及在 React 外命令式读取已提交实例的 getter。
 
 Store 仍然是普通 React Hook，可以继续使用 `useState`、`useReducer`、Context、SDK Hook 或其他 custom Hook。
 
@@ -235,12 +235,14 @@ const [useCounter, CounterProvider] = createStore(useCounterModel)
 function createStore<TStore, TProps = Record<never, never>>(
   useModel: (props: TProps) => TStore,
   options?: { tracking?: boolean },
-): readonly [StoreHook<TStore>, StoreProvider<TProps>]
+): readonly [StoreHook<TStore>, StoreProvider<TProps>, StoreGetter<TStore>]
 ```
 
 - `useModel` 必须遵守 Hooks 规则
 - 除 `children` 外的 Provider props 会传给 `useModel`
+- Provider 接受可选的 `scope?: string | number | symbol`，用于命令式查找
 - Store Hook 可不传参数使用自动追踪，也可传入返回对象的 selector
+- getter 读取最后挂载且已提交的 Provider，或 scope 精确匹配的最后一个实例；它不会订阅更新
 - 在对应 Provider 外调用会抛出明确错误
 - 支持 Strict Mode、服务端渲染和 Provider 多实例
 

package/THIRD_PARTY_NOTICES.md

@@ -2,6 +2,8 @@
 
 Kerros includes an adapted subset of `proxy-compare@3.0.1` in its access-tracking implementation.
 
+The Kerros website theme adapts the BeUI Motion segmented-control pattern in `theme/components/segmented.tsx` and its class-name utility in `theme/lib/utils.ts` from https://beui.dev (https://github.com/starc007/ui-components). This code is website-only and is not distributed with the Kerros npm package.
+
 ## proxy-compare
 
 Copyright (c) 2020 Daishi Kato
@@ -11,3 +13,13 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## BeUI Motion
+
+Copyright (c) 2026 Saurabh Chauhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/index.cjs

@@ -237,12 +237,33 @@ function createStore(useModel, options) {
 	const StoreContext = (0, react.createContext)(void 0);
 	const storeName = useModel.name || "KerrosStore";
 	const tracking = options?.tracking ?? true;
+	const registrations = [];
 	/** Run the model Hook and publish its committed snapshot */
 	const StoreProvider = (props) => {
+		const parent = (0, react.useContext)(StoreContext);
 		const { children, ...storeProps } = props;
 		const model = useModel(storeProps);
 		const [container] = (0, react.useState)(() => createStoreContainer(model));
+		const scope = props.scope;
 		useStoreLayoutEffect(() => container.publish(model), [container, model]);
+		useStoreLayoutEffect(() => {
+			const registration = {
+				container,
+				parent,
+				scope
+			};
+			const descendantIndex = registrations.findIndex((candidate) => isStoreDescendant(candidate, container, registrations));
+			if (descendantIndex < 0) registrations.push(registration);
+			else registrations.splice(descendantIndex, 0, registration);
+			return () => {
+				const index = registrations.lastIndexOf(registration);
+				if (index >= 0) registrations.splice(index, 1);
+			};
+		}, [
+			container,
+			parent,
+			scope
+		]);
 		return (0, react.createElement)(StoreContext.Provider, { value: container }, children);
 	};
 	StoreProvider.displayName = `${storeName}Provider`;
@@ -251,7 +272,28 @@ function createStore(useModel, options) {
 	const useStore = ((selector) => {
 		return useStoreValue(useStoreContext(StoreContext), selector, tracking);
 	});
-	return [useStore, StoreProvider];
+	/** Read the latest committed Store matching the optional scope */
+	const getStore = ((scope) => {
+		for (let index = registrations.length - 1; index >= 0; index--) {
+			const registration = registrations[index];
+			if (scope === void 0 || Object.is(registration.scope, scope)) return registration.container.getSnapshot();
+		}
+		throw new Error(scope === void 0 ? "Kerros store getter requires a mounted Provider" : "Kerros store getter could not find a mounted Provider for the requested scope");
+	});
+	return [
+		useStore,
+		StoreProvider,
+		getStore
+	];
+}
+/** Test whether one committed Provider is nested below another container */
+function isStoreDescendant(registration, ancestor, registrations) {
+	let parent = registration.parent;
+	while (parent) {
+		if (parent === ancestor) return true;
+		parent = registrations.find((candidate) => candidate.container === parent)?.parent;
+	}
+	return false;
 }
 function bindStore(nameOrOptions = "KerrosExternalStore", inputOptions) {
 	const name = typeof nameOrOptions === "string" ? nameOrOptions : "KerrosExternalStore";

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { FC, PropsWithChildren } from "react";
 //#region src/index.d.ts
 declare const storeHookMarker: unique symbol;
+declare const storeGetterMarker: unique symbol;
 declare const storeInstanceHookMarker: unique symbol;
 declare const externalStoreProviderMarker: unique symbol;
 /** Store behavior options */
@@ -17,8 +18,22 @@ interface StoreHook<TStore> {
   (): TStore;
   <TSelection extends object>(selector: StoreSelector<TStore, TSelection>): TSelection;
 }
+/** Supported identity for imperative Provider lookup */
+type StoreScope = string | number | symbol;
+/** Imperative reader for the latest committed Store snapshot */
+interface StoreGetter<TStore> {
+  /** Type-only Store getter identity */
+  readonly [storeGetterMarker]: TStore;
+  /** Read the most recently mounted Store */
+  (): TStore;
+  /** Read the most recently mounted Store matching one scope */
+  (scope: StoreScope): TStore;
+}
 /** Provider created for a Store hook */
-type StoreProvider<TProps> = FC<PropsWithChildren<TProps>>;
+type StoreProvider<TProps> = FC<PropsWithChildren<TProps & {
+  /** Optional identity used by the imperative Store getter */
+  scope?: StoreScope;
+}>>;
 /** Hook returning the exact external Store instance */
 interface StoreInstanceHook<TStore> {
   /** Type-only Store instance hook identity */
@@ -26,9 +41,9 @@ interface StoreInstanceHook<TStore> {
   (): TStore;
 }
 /** Provider carrying an existing external Store instance */
-type ExternalStoreProvider<TStore> = StoreProvider<{
+type ExternalStoreProvider<TStore> = FC<PropsWithChildren<{
   store: TStore;
-}> & {
+}>> & {
   /** Type-only external Store Provider identity */
   readonly [externalStoreProviderMarker]: TStore;
 };
@@ -48,11 +63,11 @@ declare function ref<T extends object>(value: T): T;
 /**
  * Create a React Store with automatic tracking and explicit selector support
  */
-declare function createStore<TStore, TProps = Record<never, never>>(useModel: (props: TProps) => TStore, options?: StoreOptions): readonly [StoreHook<TStore>, StoreProvider<TProps>];
+declare function createStore<TStore, TProps = Record<never, never>>(useModel: (props: TProps) => TStore, options?: StoreOptions): readonly [StoreHook<TStore>, StoreProvider<TProps>, StoreGetter<TStore>];
 /**
  * Bind existing external Store instances to scoped React consumers
  */
 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, StoreOptions, StoreProvider, StoreSelector, bindStore, createStore, ref };
+export { ExternalStore, ExternalStoreSnapshot, StoreBinding, StoreGetter, StoreHook, StoreOptions, StoreProvider, StoreScope, StoreSelector, bindStore, createStore, ref };

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { FC, PropsWithChildren } from "react";
 //#region src/index.d.ts
 declare const storeHookMarker: unique symbol;
+declare const storeGetterMarker: unique symbol;
 declare const storeInstanceHookMarker: unique symbol;
 declare const externalStoreProviderMarker: unique symbol;
 /** Store behavior options */
@@ -17,8 +18,22 @@ interface StoreHook<TStore> {
   (): TStore;
   <TSelection extends object>(selector: StoreSelector<TStore, TSelection>): TSelection;
 }
+/** Supported identity for imperative Provider lookup */
+type StoreScope = string | number | symbol;
+/** Imperative reader for the latest committed Store snapshot */
+interface StoreGetter<TStore> {
+  /** Type-only Store getter identity */
+  readonly [storeGetterMarker]: TStore;
+  /** Read the most recently mounted Store */
+  (): TStore;
+  /** Read the most recently mounted Store matching one scope */
+  (scope: StoreScope): TStore;
+}
 /** Provider created for a Store hook */
-type StoreProvider<TProps> = FC<PropsWithChildren<TProps>>;
+type StoreProvider<TProps> = FC<PropsWithChildren<TProps & {
+  /** Optional identity used by the imperative Store getter */
+  scope?: StoreScope;
+}>>;
 /** Hook returning the exact external Store instance */
 interface StoreInstanceHook<TStore> {
   /** Type-only Store instance hook identity */
@@ -26,9 +41,9 @@ interface StoreInstanceHook<TStore> {
   (): TStore;
 }
 /** Provider carrying an existing external Store instance */
-type ExternalStoreProvider<TStore> = StoreProvider<{
+type ExternalStoreProvider<TStore> = FC<PropsWithChildren<{
   store: TStore;
-}> & {
+}>> & {
   /** Type-only external Store Provider identity */
   readonly [externalStoreProviderMarker]: TStore;
 };
@@ -48,11 +63,11 @@ declare function ref<T extends object>(value: T): T;
 /**
  * Create a React Store with automatic tracking and explicit selector support
  */
-declare function createStore<TStore, TProps = Record<never, never>>(useModel: (props: TProps) => TStore, options?: StoreOptions): readonly [StoreHook<TStore>, StoreProvider<TProps>];
+declare function createStore<TStore, TProps = Record<never, never>>(useModel: (props: TProps) => TStore, options?: StoreOptions): readonly [StoreHook<TStore>, StoreProvider<TProps>, StoreGetter<TStore>];
 /**
  * Bind existing external Store instances to scoped React consumers
  */
 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, StoreOptions, StoreProvider, StoreSelector, bindStore, createStore, ref };
+export { ExternalStore, ExternalStoreSnapshot, StoreBinding, StoreGetter, StoreHook, StoreOptions, StoreProvider, StoreScope, StoreSelector, bindStore, createStore, ref };

package/dist/index.mjs

@@ -236,12 +236,33 @@ function createStore(useModel, options) {
 	const StoreContext = createContext(void 0);
 	const storeName = useModel.name || "KerrosStore";
 	const tracking = options?.tracking ?? true;
+	const registrations = [];
 	/** Run the model Hook and publish its committed snapshot */
 	const StoreProvider = (props) => {
+		const parent = useContext(StoreContext);
 		const { children, ...storeProps } = props;
 		const model = useModel(storeProps);
 		const [container] = useState(() => createStoreContainer(model));
+		const scope = props.scope;
 		useStoreLayoutEffect(() => container.publish(model), [container, model]);
+		useStoreLayoutEffect(() => {
+			const registration = {
+				container,
+				parent,
+				scope
+			};
+			const descendantIndex = registrations.findIndex((candidate) => isStoreDescendant(candidate, container, registrations));
+			if (descendantIndex < 0) registrations.push(registration);
+			else registrations.splice(descendantIndex, 0, registration);
+			return () => {
+				const index = registrations.lastIndexOf(registration);
+				if (index >= 0) registrations.splice(index, 1);
+			};
+		}, [
+			container,
+			parent,
+			scope
+		]);
 		return createElement(StoreContext.Provider, { value: container }, children);
 	};
 	StoreProvider.displayName = `${storeName}Provider`;
@@ -250,7 +271,28 @@ function createStore(useModel, options) {
 	const useStore = ((selector) => {
 		return useStoreValue(useStoreContext(StoreContext), selector, tracking);
 	});
-	return [useStore, StoreProvider];
+	/** Read the latest committed Store matching the optional scope */
+	const getStore = ((scope) => {
+		for (let index = registrations.length - 1; index >= 0; index--) {
+			const registration = registrations[index];
+			if (scope === void 0 || Object.is(registration.scope, scope)) return registration.container.getSnapshot();
+		}
+		throw new Error(scope === void 0 ? "Kerros store getter requires a mounted Provider" : "Kerros store getter could not find a mounted Provider for the requested scope");
+	});
+	return [
+		useStore,
+		StoreProvider,
+		getStore
+	];
+}
+/** Test whether one committed Provider is nested below another container */
+function isStoreDescendant(registration, ancestor, registrations) {
+	let parent = registration.parent;
+	while (parent) {
+		if (parent === ancestor) return true;
+		parent = registrations.find((candidate) => candidate.container === parent)?.parent;
+	}
+	return false;
 }
 function bindStore(nameOrOptions = "KerrosExternalStore", inputOptions) {
 	const name = typeof nameOrOptions === "string" ? nameOrOptions : "KerrosExternalStore";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@violetflux/kerros",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Hook-native state sharing for React with automatic access tracking and focused selectors.",
   "keywords": [
     "react",
@@ -84,18 +84,24 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
+    "@rsbuild/plugin-tailwindcss": "^2.0.3",
     "@rspress/core": "2.0.17",
+    "@tabler/icons-react": "^3.46.0",
     "@types/jsdom": "28.0.3",
     "@types/node": "26.1.1",
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
     "@types/use-sync-external-store": "1.5.0",
+    "clsx": "^2.1.1",
     "eslint": "10.7.0",
     "eslint-plugin-react-hooks": "7.1.1",
     "globals": "17.7.0",
     "jsdom": "29.1.1",
+    "motion": "^13.1.0",
     "react": "19.2.7",
     "react-dom": "19.2.7",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.3",
     "tinybench": "6.1.2",
     "tsdown": "0.22.9",
     "typescript": "5.9.3",

package/skills/kerros/SKILL.md

@@ -45,7 +45,7 @@ function useCounterModel() {
   return { count, increment }
 }
 
-export const [useCounter, CounterProvider] = createStore(useCounterModel)
+export const [useCounter, CounterProvider, getCounter] = createStore(useCounterModel)
 ```
 
 Mount the Provider at the narrowest ancestor shared by all consumers:
@@ -72,6 +72,18 @@ function Counter() {
 
 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.
 
+Use the third return value only for imperative work outside React. `getCounter()` reads the most recently mounted committed Provider; pass a `string`, `number`, or `symbol` scope to select the latest matching Provider:
+
+```tsx
+<CounterProvider scope="main">
+  <App />
+</CounterProvider>
+
+getCounter('main').increment()
+```
+
+The getter does not subscribe and is unavailable before commit, after unmount, or during SSR. Call it at execution time; do not cache its result as a live state source. Duplicate scopes shadow and fall back in mount order. Keep using the Store Hook for rendered state.
+
 ## Subscription modes
 
 - `useStore()` is the default and returns a read-only tracked render snapshot. It may be destructured, kept in a render-local variable, returned from a custom Hook, or passed to a synchronously rendered child. Do not mutate it or retain it as a live state object; spread, rest destructuring, enumeration, and serialization create broad subscriptions.
@@ -177,6 +189,7 @@ function Providers({ children }: PropsWithChildren) {
 - 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 use a Store getter for reactive rendering. It exposes only committed mounted instances, throws when none match, and selects by mount priority rather than Context ancestry.
 - 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 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.