@violetflux/kerros 0.2.3 → 0.3.0

package/README.de.md

@@ -81,13 +81,17 @@ 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.
 
 ## Dokumentation

package/README.es.md

@@ -81,13 +81,17 @@ 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`.
 
 ## Documentación

package/README.fr.md

@@ -81,13 +81,17 @@ 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`.
 
 ## Documentation

package/README.ja.md

@@ -82,13 +82,17 @@ 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,17 @@ 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.
 
@@ -154,6 +154,8 @@ const { count, setCount } = useCounter()
 
 Primitive snapshots use `Object.is`. `Map`, `Set`, class instances, and other non-plain objects are treated as atomic references. Store and external Store snapshots must be immutable: publish a new reference for every observable change.
 
+React elements and portals are atomic automatically. Standard `useRef()` and `createRef()` containers can be returned directly in React 17, 18, and 19. Use `ref(value)` only for Proxy-intolerant third-party objects or strict identity; internal mutation of an atomic value is not reactive.
+
 The selector-free result is the component's read-only tracked snapshot. You may destructure it, keep it in a render-local variable, or pass it to a synchronously rendered child. Do not mutate it or retain it in state, refs, module variables, or long-lived caches as a live state object; spread, rest destructuring, enumeration, and serialization create broad subscriptions. Reactive Effects should read values during render and declare correct dependencies. Use `useInstance()` only for imperative latest-state reads that do not drive rendering, and never expose an Effect Event as a public Store action.
 
 ## Multiple instances
@@ -241,15 +243,25 @@ 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
 
+### `ref` (identity escape hatch)
+
+```ts
+function ref<T extends object>(value: T): T
+```
+
+Marks an object as atomic and returns the exact same identity. Standard React refs do not need this helper.
+
 ### 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.

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。
 
@@ -146,6 +146,8 @@ const { count, setCount } = useCounter()
 
 基础类型快照使用 `Object.is`。`Map`、`Set`、类实例及其他非普通对象按整体引用处理。Store 和 External Store 快照必须保持不可变：每次可观察变化都发布新引用。
 
+React Element 和 Portal 会自动作为原子值处理。React 17、18、19 的标准 `useRef()`、`createRef()` 容器可以直接返回。只有第三方对象不能接受 Proxy，或者必须保留严格身份时才使用 `ref(value)`；原子值的内部原地修改不是响应式更新。
+
 无 selector 的结果是当前组件的只读追踪快照，可以直接解构、保存在渲染局部变量中，或传给同步渲染的子组件继续读取。不要修改快照，也不要把它保存到 state、ref、模块变量或长期缓存后当作实时状态源；展开、rest 解构、枚举和序列化会形成宽泛订阅。响应式 Effect 应在渲染期间读取值并声明正确依赖；只有不参与渲染、需要执行时读取最新状态的命令式逻辑才使用 `useInstance()`。也不要把 Effect Event 暴露成公共 Store action。
 
 ## 多个实例
@@ -233,15 +235,25 @@ 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 多实例
 
+### `ref`（身份逃生口）
+
+```ts
+function ref<T extends object>(value: T): T
+```
+
+把对象标记为原子值并返回完全相同的身份。标准 React ref 不需要这个辅助函数。
+
 ### 高级用法：绑定已有 External Store
 
 绝大多数应用只需要 `createStore`。只有当某个库或 SDK 已经在 React 外持有权威状态，并提供稳定的 `getSnapshot` 和 `subscribe` 函数时，才使用 `bindStore`。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,25 @@
+# Third-party notices
+
+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
+
+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.
+
+## 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

@@ -1,7 +1,164 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let react = require("react");
-let proxy_compare = require("proxy-compare");
 let use_sync_external_store_shim_with_selector = require("use-sync-external-store/shim/with-selector");
+//#region src/access-tracking.ts
+/*!
+* Adapted from proxy-compare 3.0.1.
+* Copyright (c) 2020 Daishi Kato. Licensed under the MIT License.
+*/
+const trackMemoSymbol = Symbol();
+const getOriginalSymbol = Symbol();
+const reactElementType = Symbol.for("react.element");
+const reactTransitionalElementType = Symbol.for("react.transitional.element");
+const reactPortalType = Symbol.for("react.portal");
+const objectPrototype = Object.prototype;
+const arrayPrototype = Array.prototype;
+const trackingOverrides = /* @__PURE__ */ new WeakMap();
+/** Create an access-tracking Proxy and lazily preserve React atomic values */
+function createProxy(value, affected, proxyCache, targetCache) {
+	if (!isObjectToTrack(value)) return value;
+	const typedTargetCache = targetCache;
+	let targetAndCopied = typedTargetCache?.get(value);
+	if (!targetAndCopied) {
+		const target = getOriginalObject(value);
+		targetAndCopied = needsToCopyTargetObject(target) ? [target, copyTargetObject(target)] : [target];
+		typedTargetCache?.set(value, targetAndCopied);
+	}
+	const [target, copiedTarget] = targetAndCopied;
+	const typedProxyCache = proxyCache;
+	let handlerAndState = typedProxyCache?.get(target);
+	if (!handlerAndState || handlerAndState[1].copied !== Boolean(copiedTarget)) {
+		handlerAndState = createProxyHandler(target, Boolean(copiedTarget));
+		handlerAndState[1].proxy = new Proxy(copiedTarget ?? target, handlerAndState[0]);
+		typedProxyCache?.set(target, handlerAndState);
+	}
+	handlerAndState[1].affected = affected;
+	handlerAndState[1].proxyCache = proxyCache;
+	handlerAndState[1].targetCache = targetCache;
+	return handlerAndState[1].proxy;
+}
+/** Compare only paths read through a previous tracking Proxy */
+function isChanged(previous, next, affected, cache, isEqual = Object.is) {
+	if (isEqual(previous, next)) return false;
+	if (!isObject(previous) || !isObject(next)) return true;
+	const used = affected.get(getOriginalObject(previous));
+	if (!used) return true;
+	if (cache) {
+		if (cache.get(previous) === next) return false;
+		cache.set(previous, next);
+	}
+	let changed = null;
+	for (const key of used.has ?? []) {
+		changed = Reflect.has(previous, key) !== Reflect.has(next, key);
+		if (changed) return true;
+	}
+	if (used.all) {
+		changed = areOwnKeysChanged(previous, next);
+		if (changed) return true;
+	} else for (const key of used.own ?? []) {
+		changed = Boolean(Reflect.getOwnPropertyDescriptor(previous, key)) !== Boolean(Reflect.getOwnPropertyDescriptor(next, key));
+		if (changed) return true;
+	}
+	for (const key of used.keys ?? []) {
+		changed = isChanged(Reflect.get(previous, key), Reflect.get(next, key), affected, cache, isEqual);
+		if (changed) return true;
+	}
+	if (changed === null) throw new Error("Invalid Kerros access tracking state");
+	return changed;
+}
+/** Mark an exact object identity as tracked or atomic */
+function markToTrack(value, track = true) {
+	trackingOverrides.set(value, track);
+}
+/** Build the handler state shared by a single cached Proxy */
+function createProxyHandler(original, copied) {
+	const state = { copied };
+	let trackWholeObject = false;
+	/** Record one access operation against the original snapshot object */
+	const record = (operation, key) => {
+		if (trackWholeObject) return;
+		let used = state.affected?.get(original);
+		if (!used) {
+			used = {};
+			state.affected?.set(original, used);
+		}
+		if (operation === "all") {
+			used.all = true;
+			return;
+		}
+		let keys = used[operation];
+		if (!keys) {
+			keys = /* @__PURE__ */ new Set();
+			used[operation] = keys;
+		}
+		keys.add(key);
+	};
+	const handler = {
+		get: (target, key) => {
+			if (key === getOriginalSymbol) return original;
+			record("keys", key);
+			return createProxy(Reflect.get(target, key), state.affected, state.proxyCache, state.targetCache);
+		},
+		getOwnPropertyDescriptor: (target, key) => {
+			record("own", key);
+			return Reflect.getOwnPropertyDescriptor(target, key);
+		},
+		has: (target, key) => {
+			if (key === trackMemoSymbol) {
+				trackWholeObject = true;
+				state.affected?.delete(original);
+				return true;
+			}
+			record("has", key);
+			return Reflect.has(target, key);
+		},
+		ownKeys: (target) => {
+			record("all");
+			return Reflect.ownKeys(target);
+		}
+	};
+	if (copied) {
+		handler.deleteProperty = () => false;
+		handler.set = () => false;
+	}
+	return [handler, state];
+}
+/** Decide lazily whether one reached value supports recursive tracking */
+function isObjectToTrack(value) {
+	if (!isObject(value)) return false;
+	if (trackingOverrides.has(value)) return trackingOverrides.get(value);
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype === arrayPrototype) return true;
+	if (prototype !== objectPrototype) return false;
+	const marker = value.$$typeof;
+	return marker !== reactElementType && marker !== reactTransitionalElementType && marker !== reactPortalType;
+}
+/** Narrow mutable object operations used by the compare algorithm */
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+/** Unwrap a cached tracking Proxy when comparison receives one */
+function getOriginalObject(value) {
+	return value[getOriginalSymbol] ?? value;
+}
+/** Detect invariant-sensitive frozen properties before Proxy creation */
+function needsToCopyTargetObject(value) {
+	return Object.values(Object.getOwnPropertyDescriptors(value)).some((descriptor) => !descriptor.configurable && !descriptor.writable);
+}
+/** Copy an invariant-sensitive object with configurable descriptors */
+function copyTargetObject(value) {
+	if (Array.isArray(value)) return Array.from(value);
+	const descriptors = Object.getOwnPropertyDescriptors(value);
+	for (const descriptor of Object.values(descriptors)) descriptor.configurable = true;
+	return Object.create(Object.getPrototypeOf(value), descriptors);
+}
+/** Compare complete own-key enumeration in insertion order */
+function areOwnKeysChanged(previous, next) {
+	const previousKeys = Reflect.ownKeys(previous);
+	const nextKeys = Reflect.ownKeys(next);
+	return previousKeys.length !== nextKeys.length || previousKeys.some((key, index) => key !== nextKeys[index]);
+}
+//#endregion
 //#region src/tracking.ts
 const useStoreLayoutEffect$1 = typeof window === "undefined" ? react.useEffect : react.useLayoutEffect;
 const proxyTargetCache = /* @__PURE__ */ new WeakMap();
@@ -23,12 +180,12 @@ function useStoreValue(store, selector, tracking) {
 		if (selector || !tracking) return shallowEqual(previous, next);
 		const committed = committedTracking.current;
 		if (!committed) return Object.is(previous, next);
-		return !(0, proxy_compare.isChanged)(committed.snapshot, next, committed.affected, /* @__PURE__ */ new WeakMap());
+		return !isChanged(committed.snapshot, next, committed.affected, /* @__PURE__ */ new WeakMap());
 	}, [selector, tracking]);
 	const snapshot = (0, use_sync_external_store_shim_with_selector.useSyncExternalStoreWithSelector)(store.subscribe, store.getSnapshot, store.getSnapshot, selectSnapshot, compareSelections);
 	const affected = /* @__PURE__ */ new WeakMap();
 	const shouldTrack = !selector && tracking;
-	const value = shouldTrack ? (0, proxy_compare.createProxy)(snapshot, affected, proxyCache, proxyTargetCache) : snapshot;
+	const value = shouldTrack ? createProxy(snapshot, affected, proxyCache, proxyTargetCache) : snapshot;
 	useStoreLayoutEffect$1(() => {
 		if (shouldTrack) {
 			const renderedSnapshot = snapshot;
@@ -37,7 +194,7 @@ function useStoreValue(store, selector, tracking) {
 				snapshot: renderedSnapshot
 			};
 			const currentSnapshot = store.getSnapshot();
-			if (!Object.is(renderedSnapshot, currentSnapshot) && (0, proxy_compare.isChanged)(renderedSnapshot, currentSnapshot, affected, /* @__PURE__ */ new WeakMap())) calibrate(currentSnapshot);
+			if (!Object.is(renderedSnapshot, currentSnapshot) && isChanged(renderedSnapshot, currentSnapshot, affected, /* @__PURE__ */ new WeakMap())) calibrate(currentSnapshot);
 		}
 	}, [
 		affected,
@@ -67,6 +224,11 @@ function isShallowComparable(value) {
 }
 //#endregion
 //#region src/index.tsx
+/** Preserve an exact object identity and compare it as one atomic Store value */
+function ref(value) {
+	markToTrack(value, false);
+	return value;
+}
 const useStoreLayoutEffect = typeof window === "undefined" ? react.useEffect : react.useLayoutEffect;
 /**
 * Create a React Store with automatic tracking and explicit selector support
@@ -75,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`;
@@ -89,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";
@@ -144,3 +348,4 @@ function useStoreContext(context) {
 //#endregion
 exports.bindStore = bindStore;
 exports.createStore = createStore;
+exports.ref = ref;

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;
 };
@@ -43,14 +58,16 @@ interface ExternalStore<TSnapshot> {
 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>, ExternalStoreProvider<TStore>, StoreInstanceHook<TStore>];
+/** Preserve an exact object identity and compare it as one atomic Store value */
+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 };
+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;
 };
@@ -43,14 +58,16 @@ interface ExternalStore<TSnapshot> {
 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>, ExternalStoreProvider<TStore>, StoreInstanceHook<TStore>];
+/** Preserve an exact object identity and compare it as one atomic Store value */
+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 };
+export { ExternalStore, ExternalStoreSnapshot, StoreBinding, StoreGetter, StoreHook, StoreOptions, StoreProvider, StoreScope, StoreSelector, bindStore, createStore, ref };

package/dist/index.mjs

@@ -1,6 +1,163 @@
 import { createContext, createElement, useCallback, useContext, useEffect, useLayoutEffect, useReducer, useRef, useState } from "react";
-import { createProxy, isChanged } from "proxy-compare";
 import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector";
+//#region src/access-tracking.ts
+/*!
+* Adapted from proxy-compare 3.0.1.
+* Copyright (c) 2020 Daishi Kato. Licensed under the MIT License.
+*/
+const trackMemoSymbol = Symbol();
+const getOriginalSymbol = Symbol();
+const reactElementType = Symbol.for("react.element");
+const reactTransitionalElementType = Symbol.for("react.transitional.element");
+const reactPortalType = Symbol.for("react.portal");
+const objectPrototype = Object.prototype;
+const arrayPrototype = Array.prototype;
+const trackingOverrides = /* @__PURE__ */ new WeakMap();
+/** Create an access-tracking Proxy and lazily preserve React atomic values */
+function createProxy(value, affected, proxyCache, targetCache) {
+	if (!isObjectToTrack(value)) return value;
+	const typedTargetCache = targetCache;
+	let targetAndCopied = typedTargetCache?.get(value);
+	if (!targetAndCopied) {
+		const target = getOriginalObject(value);
+		targetAndCopied = needsToCopyTargetObject(target) ? [target, copyTargetObject(target)] : [target];
+		typedTargetCache?.set(value, targetAndCopied);
+	}
+	const [target, copiedTarget] = targetAndCopied;
+	const typedProxyCache = proxyCache;
+	let handlerAndState = typedProxyCache?.get(target);
+	if (!handlerAndState || handlerAndState[1].copied !== Boolean(copiedTarget)) {
+		handlerAndState = createProxyHandler(target, Boolean(copiedTarget));
+		handlerAndState[1].proxy = new Proxy(copiedTarget ?? target, handlerAndState[0]);
+		typedProxyCache?.set(target, handlerAndState);
+	}
+	handlerAndState[1].affected = affected;
+	handlerAndState[1].proxyCache = proxyCache;
+	handlerAndState[1].targetCache = targetCache;
+	return handlerAndState[1].proxy;
+}
+/** Compare only paths read through a previous tracking Proxy */
+function isChanged(previous, next, affected, cache, isEqual = Object.is) {
+	if (isEqual(previous, next)) return false;
+	if (!isObject(previous) || !isObject(next)) return true;
+	const used = affected.get(getOriginalObject(previous));
+	if (!used) return true;
+	if (cache) {
+		if (cache.get(previous) === next) return false;
+		cache.set(previous, next);
+	}
+	let changed = null;
+	for (const key of used.has ?? []) {
+		changed = Reflect.has(previous, key) !== Reflect.has(next, key);
+		if (changed) return true;
+	}
+	if (used.all) {
+		changed = areOwnKeysChanged(previous, next);
+		if (changed) return true;
+	} else for (const key of used.own ?? []) {
+		changed = Boolean(Reflect.getOwnPropertyDescriptor(previous, key)) !== Boolean(Reflect.getOwnPropertyDescriptor(next, key));
+		if (changed) return true;
+	}
+	for (const key of used.keys ?? []) {
+		changed = isChanged(Reflect.get(previous, key), Reflect.get(next, key), affected, cache, isEqual);
+		if (changed) return true;
+	}
+	if (changed === null) throw new Error("Invalid Kerros access tracking state");
+	return changed;
+}
+/** Mark an exact object identity as tracked or atomic */
+function markToTrack(value, track = true) {
+	trackingOverrides.set(value, track);
+}
+/** Build the handler state shared by a single cached Proxy */
+function createProxyHandler(original, copied) {
+	const state = { copied };
+	let trackWholeObject = false;
+	/** Record one access operation against the original snapshot object */
+	const record = (operation, key) => {
+		if (trackWholeObject) return;
+		let used = state.affected?.get(original);
+		if (!used) {
+			used = {};
+			state.affected?.set(original, used);
+		}
+		if (operation === "all") {
+			used.all = true;
+			return;
+		}
+		let keys = used[operation];
+		if (!keys) {
+			keys = /* @__PURE__ */ new Set();
+			used[operation] = keys;
+		}
+		keys.add(key);
+	};
+	const handler = {
+		get: (target, key) => {
+			if (key === getOriginalSymbol) return original;
+			record("keys", key);
+			return createProxy(Reflect.get(target, key), state.affected, state.proxyCache, state.targetCache);
+		},
+		getOwnPropertyDescriptor: (target, key) => {
+			record("own", key);
+			return Reflect.getOwnPropertyDescriptor(target, key);
+		},
+		has: (target, key) => {
+			if (key === trackMemoSymbol) {
+				trackWholeObject = true;
+				state.affected?.delete(original);
+				return true;
+			}
+			record("has", key);
+			return Reflect.has(target, key);
+		},
+		ownKeys: (target) => {
+			record("all");
+			return Reflect.ownKeys(target);
+		}
+	};
+	if (copied) {
+		handler.deleteProperty = () => false;
+		handler.set = () => false;
+	}
+	return [handler, state];
+}
+/** Decide lazily whether one reached value supports recursive tracking */
+function isObjectToTrack(value) {
+	if (!isObject(value)) return false;
+	if (trackingOverrides.has(value)) return trackingOverrides.get(value);
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype === arrayPrototype) return true;
+	if (prototype !== objectPrototype) return false;
+	const marker = value.$$typeof;
+	return marker !== reactElementType && marker !== reactTransitionalElementType && marker !== reactPortalType;
+}
+/** Narrow mutable object operations used by the compare algorithm */
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+/** Unwrap a cached tracking Proxy when comparison receives one */
+function getOriginalObject(value) {
+	return value[getOriginalSymbol] ?? value;
+}
+/** Detect invariant-sensitive frozen properties before Proxy creation */
+function needsToCopyTargetObject(value) {
+	return Object.values(Object.getOwnPropertyDescriptors(value)).some((descriptor) => !descriptor.configurable && !descriptor.writable);
+}
+/** Copy an invariant-sensitive object with configurable descriptors */
+function copyTargetObject(value) {
+	if (Array.isArray(value)) return Array.from(value);
+	const descriptors = Object.getOwnPropertyDescriptors(value);
+	for (const descriptor of Object.values(descriptors)) descriptor.configurable = true;
+	return Object.create(Object.getPrototypeOf(value), descriptors);
+}
+/** Compare complete own-key enumeration in insertion order */
+function areOwnKeysChanged(previous, next) {
+	const previousKeys = Reflect.ownKeys(previous);
+	const nextKeys = Reflect.ownKeys(next);
+	return previousKeys.length !== nextKeys.length || previousKeys.some((key, index) => key !== nextKeys[index]);
+}
+//#endregion
 //#region src/tracking.ts
 const useStoreLayoutEffect$1 = typeof window === "undefined" ? useEffect : useLayoutEffect;
 const proxyTargetCache = /* @__PURE__ */ new WeakMap();
@@ -66,6 +223,11 @@ function isShallowComparable(value) {
 }
 //#endregion
 //#region src/index.tsx
+/** Preserve an exact object identity and compare it as one atomic Store value */
+function ref(value) {
+	markToTrack(value, false);
+	return value;
+}
 const useStoreLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 /**
 * Create a React Store with automatic tracking and explicit selector support
@@ -74,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`;
@@ -88,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";
@@ -141,4 +345,4 @@ function useStoreContext(context) {
 	return store;
 }
 //#endregion
-export { bindStore, createStore };
+export { bindStore, createStore, ref };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@violetflux/kerros",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Hook-native state sharing for React with automatic access tracking and focused selectors.",
   "keywords": [
     "react",
@@ -32,7 +32,8 @@
   "sideEffects": false,
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -79,23 +80,28 @@
     "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "proxy-compare": "3.0.1",
     "use-sync-external-store": "1.6.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
+    "@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.
@@ -79,6 +91,13 @@ Kerros automatically tracks object, array, and nested property reads made during
 - `createStore(model, { tracking: false })` and `bindStore({ tracking: false })` disable automatic tracking for selector-free calls and compare the complete Store at the top level instead.
 - Primitive Store snapshots use `Object.is`. `Map`, `Set`, class instances, and other atomic objects are tracked by reference as a whole.
 
+## React and identity-sensitive values
+
+- Return standard `useRef()` and `createRef()` containers directly. They work with DOM refs, `forwardRef`, and `useImperativeHandle` in React 17, 18, and 19; do not wrap them by default.
+- React elements and portals are detected lazily and returned as atomic values without a Proxy.
+- Import `ref` from `@violetflux/kerros` only for a third-party object that cannot tolerate a Proxy or when strict object identity must survive the tracked snapshot.
+- `ref(value)`, `Map`, `Set`, and class instances are non-reactive internally. Publish a new containing-field reference for observable changes; changing a React ref's `.current` also does not rerender.
+
 ## 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.
@@ -163,13 +182,14 @@ 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.
-- Prefer selector-free reads with immediate destructuring. Do not let the tracked result escape render through saving, returning, spreading, serializing, or passing it as an argument.
+- Prefer selector-free reads with immediate destructuring. A tracked value may continue through a custom Hook or synchronously rendered child, but must not escape the render chain through state, refs, module variables, long-lived caches, Effects, or deferred callbacks. Spreading, rest destructuring, enumeration, and serialization create broad subscriptions.
 - When an explicit selector is justified, return an object of concrete fields and actions. Do not use array selectors or select the complete Store.
 - Do not wrap inline selectors with `useCallback`; Kerros handles selector identity.
 - Keep public actions as ordinary functions unless their reference stability is an explicit producer-side requirement. In React 19, use `useEffectEvent` only for events called from Effects, never as a public Store action.
 - Do not mirror the same mutable state across Stores. Read it from its authoritative Store or move ownership.
 - 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.