@violetflux/kerros 0.2.2 → 0.2.4

package/README.de.md

@@ -88,6 +88,8 @@ 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.
 
+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

@@ -88,6 +88,8 @@ 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.
 
+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

@@ -88,6 +88,8 @@ 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.
 
+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

@@ -89,6 +89,8 @@ const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 
 返される Store Hook は引数なしで自動追跡を使います。明示的なオブジェクト selector は派生値や計測済みホットスポット向けです。対応する Provider の外では明確なエラーを送出します。
 
+React Element と Portal は自動的に原子的な値になります。`useRef()` と `createRef()` はそのまま返せます。`ref(value)` は Proxy 非互換の値や厳密な同一性が必要な場合だけ使います。
+
 高度な連携として、既存の Headless External Store にだけ `bindStore` を使います。通常の Hook 状態には `createStore` を使ってください。Context は元の Store インスタンスだけを保持し、コンシューマーは `getSnapshot` と `subscribe` を直接利用します。
 
 ## ドキュメント

package/README.ko.md

@@ -89,6 +89,8 @@ const [useStream, StreamProvider] = bindStore<Stream>('Stream')
 
 반환된 Store Hook은 인자 없이 자동 추적을 사용합니다. 명시적 객체 selector는 파생 값과 측정된 핫스팟을 위한 고급 경로입니다. Provider 밖에서 호출하면 명확한 오류가 발생합니다.
 
+React Element와 Portal은 자동으로 원자 값이 됩니다. `useRef()`와 `createRef()`는 그대로 반환할 수 있으며 `ref(value)`는 Proxy 비호환 값이나 엄격한 동일성이 필요할 때만 사용합니다.
+
 고급 통합이 필요한 기존 Headless External Store에만 `bindStore`를 사용하세요. 일반 Hook 상태에는 `createStore`를 사용합니다. Context는 원래 Store 인스턴스만 보관하고 소비자는 `getSnapshot`과 `subscribe`를 직접 사용합니다.
 
 ## 문서

package/README.md

@@ -154,7 +154,9 @@ 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.
 
-Do not save, return, spread, serialize, or pass the complete selector-free result around. Read properties immediately, normally by destructuring. Effects and `useEffectEvent` may perform imperative reads from `useInstance()`, but rendered state must use the subscribed Store Hook; never expose an Effect Event as a public Store action.
+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
 
@@ -250,6 +252,14 @@ function createStore<TStore, TProps = Record<never, never>>(
 - 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.
@@ -286,7 +296,7 @@ import kerros from '@violetflux/eslint-plugin-kerros'
 export default [kerros.configs.recommendedTypeChecked]
 ```
 
-`recommendedTypeChecked` enables all 17 rules as errors and uses TypeScript `projectService`. Very large repositories may use `kerros.configs.fastTypeChecked`, which keeps type-aware Store recognition but disables the most expensive whole-program and deep analyses. See the [measured ESLint benchmark](https://github.com/violetflux/kerros/blob/main/benchmarks/eslint/RESULTS.md); the fast profile is a tradeoff, not an untyped fallback. The plugin analyzes complete TS/TSX files, not incomplete Markdown snippets.
+`recommendedTypeChecked` enables all 16 rules as errors and uses TypeScript `projectService`. Very large repositories may use `kerros.configs.fastTypeChecked`, which keeps type-aware Store recognition but disables the most expensive whole-program and deep analyses. See the [measured ESLint benchmark](https://github.com/violetflux/kerros/blob/main/benchmarks/eslint/RESULTS.md); the fast profile is a tradeoff, not an untyped fallback. The plugin analyzes complete TS/TSX files, not incomplete Markdown snippets.
 
 For maintainers, npm Trusted Publisher entries must be configured for both `@violetflux/kerros` and `@violetflux/eslint-plugin-kerros`. That npm-side configuration is the only release step outside this repository; CI checks and publishes the runtime first, then the plugin.
 

package/README.zh-CN.md

@@ -146,7 +146,9 @@ const { count, setCount } = useCounter()
 
 基础类型快照使用 `Object.is`。`Map`、`Set`、类实例及其他非普通对象按整体引用处理。Store 和 External Store 快照必须保持不可变：每次可观察变化都发布新引用。
 
-不要保存、返回、展开、序列化或传递无 selector 的完整结果；应立即读取属性，通常直接解构。Effect 与 `useEffectEvent` 可以通过 `useInstance()` 做命令式读取，但参与渲染的状态必须使用订阅 Hook；也不要把 Effect Event 暴露成公共 Store action。
+React Element 和 Portal 会自动作为原子值处理。React 17、18、19 的标准 `useRef()`、`createRef()` 容器可以直接返回。只有第三方对象不能接受 Proxy，或者必须保留严格身份时才使用 `ref(value)`；原子值的内部原地修改不是响应式更新。
+
+无 selector 的结果是当前组件的只读追踪快照，可以直接解构、保存在渲染局部变量中，或传给同步渲染的子组件继续读取。不要修改快照，也不要把它保存到 state、ref、模块变量或长期缓存后当作实时状态源；展开、rest 解构、枚举和序列化会形成宽泛订阅。响应式 Effect 应在渲染期间读取值并声明正确依赖；只有不参与渲染、需要执行时读取最新状态的命令式逻辑才使用 `useInstance()`。也不要把 Effect Event 暴露成公共 Store action。
 
 ## 多个实例
 
@@ -242,6 +244,14 @@ function createStore<TStore, TProps = Record<never, never>>(
 - 在对应 Provider 外调用会抛出明确错误
 - 支持 Strict Mode、服务端渲染和 Provider 多实例
 
+### `ref`（身份逃生口）
+
+```ts
+function ref<T extends object>(value: T): T
+```
+
+把对象标记为原子值并返回完全相同的身份。标准 React ref 不需要这个辅助函数。
+
 ### 高级用法：绑定已有 External Store
 
 绝大多数应用只需要 `createStore`。只有当某个库或 SDK 已经在 React 外持有权威状态，并提供稳定的 `getSnapshot` 和 `subscribe` 函数时，才使用 `bindStore`。
@@ -278,7 +288,7 @@ import kerros from '@violetflux/eslint-plugin-kerros'
 export default [kerros.configs.recommendedTypeChecked]
 ```
 
-`recommendedTypeChecked` 把全部 17 条规则设为 error，并启用 TypeScript `projectService`。超大型仓库可改用 `kerros.configs.fastTypeChecked`：它仍然通过类型识别真实 Kerros Hook，只关闭最昂贵的全程序与深层分析。请参考[真实 ESLint 压测](https://github.com/violetflux/kerros/blob/main/benchmarks/eslint/RESULTS.md)；fast 是性能取舍，不是不可靠的命名降级。插件首版只分析完整 TS/TSX 文件，不分析不完整 Markdown 代码块。
+`recommendedTypeChecked` 把全部 16 条规则设为 error，并启用 TypeScript `projectService`。超大型仓库可改用 `kerros.configs.fastTypeChecked`：它仍然通过类型识别真实 Kerros Hook，只关闭最昂贵的全程序与深层分析。请参考[真实 ESLint 压测](https://github.com/violetflux/kerros/blob/main/benchmarks/eslint/RESULTS.md)；fast 是性能取舍，不是不可靠的命名降级。插件首版只分析完整 TS/TSX 文件，不分析不完整 Markdown 代码块。
 
 维护者还需要分别为 `@violetflux/kerros` 和 `@violetflux/eslint-plugin-kerros` 配置 npm Trusted Publisher。这是唯一的仓库外发布步骤；仓库内工作流会先检查并发布运行库，再发布插件。
 

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,13 @@
+# Third-party notices
+
+Kerros includes an adapted subset of `proxy-compare@3.0.1` in its access-tracking implementation.
+
+## 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.

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
@@ -144,3 +306,4 @@ function useStoreContext(context) {
 //#endregion
 exports.bindStore = bindStore;
 exports.createStore = createStore;
+exports.ref = ref;

package/dist/index.d.cts

@@ -43,6 +43,8 @@ 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
  */
@@ -53,4 +55,4 @@ declare function createStore<TStore, TProps = Record<never, never>>(useModel: (p
 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, StoreHook, StoreOptions, StoreProvider, StoreSelector, bindStore, createStore, ref };

package/dist/index.d.mts

@@ -43,6 +43,8 @@ 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
  */
@@ -53,4 +55,4 @@ declare function createStore<TStore, TProps = Record<never, never>>(useModel: (p
 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, StoreHook, StoreOptions, StoreProvider, 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
@@ -141,4 +303,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.2",
+  "version": "0.2.4",
   "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,7 +80,6 @@
     "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "proxy-compare": "3.0.1",
     "use-sync-external-store": "1.6.0"
   },
   "devDependencies": {

package/skills/kerros/SKILL.md

@@ -74,11 +74,18 @@ Kerros automatically tracks object, array, and nested property reads made during
 
 ## Subscription modes
 
-- `useStore()` is the default. Read properties immediately, normally through destructuring. Do not save, return, spread, serialize, or pass the complete tracked result.
+- `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.
 - `useStore(s => ({ ... }))` is the advanced path for derived values or measured hot spots. Keep the selector inline, name its parameter `s`, and return an object whose top-level fields are shallowly compared with `Object.is`.
 - `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.
@@ -101,7 +108,7 @@ Mount the original instance without mirroring its snapshot:
 </StreamBindingProvider>
 ```
 
-Use `useStream()` with immediate property access for ordinary snapshot reads; use an explicit selector only for derived values or measured hot spots. 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.
+Treat `useStream()` as a read-only tracked render snapshot: destructure it, keep it in a render-local variable, return it from a custom Hook, or pass it to a synchronously rendered child. Use an explicit selector only for derived values or measured hot spots. Do not mutate the snapshot or retain it as a live state object. Use `useStreamInstance()` only in Provider descendants that need imperative commands, imperative latest-state reads that do not drive rendering, 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.
 
@@ -163,7 +170,7 @@ 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.