chem-rx 0.1.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## 0.3.0 - 2026-06-14
+
+### Added
+
+- `useSelector(atom, selector, equals?)` React hook (`chem-rx/react`): derive any
+  value from an atom with a selector function and re-render only when the selected
+  value changes. The optional `equals` comparator (defaults to `Object.is`) dedupes
+  re-renders by content, so an atom that churns references on every update only
+  re-renders the component when the selected slice is not equal. See
+  [useSelector](./README.md#useselector).
+
+### Removed (breaking)
+
+- Removed `useSelectAtom`. Migrate to `useSelector` with a selector function:
+  `useSelectAtom(atom, 'key')` becomes `useSelector(atom, (s) => s.key)`.
+
+## 0.2.0 - 2026-06-13
+
+### Added
+
+- Optional `equals` comparator on every atom creation path: `Atom(value, { equals })`,
+  `atom.derive(fn, { equals })`, and `atom.select(key, { equals })`. Supply a
+  content comparator to dedup notifications by data instead of identity. See
+  [Equality & change detection](./README.md#equality--change-detection).
+- `Atom()`'s second argument now also accepts an options object
+  (`{ readOnly?, equals? }`) in addition to the legacy `readOnly` boolean.
+- Exported `Equals<T>` and `AtomFactoryOptions<T>` types.
+
+### Changed (breaking)
+
+- Every atom now decides whether to notify subscribers using an equality
+  comparator that **defaults to `Object.is`**:
+  - A base atom no longer re-emits when `next()` is called with an
+    `Object.is`-equal value (previously every `next()` notified).
+  - `derive` no longer re-emits when its computed output is `Object.is`-equal
+    (previously it re-emitted on every parent update).
+  - `select` and `combine` are unchanged in practice (already `Object.is`).
+
+  Migration: pass `equals: () => false` to restore the previous always-notify
+  behavior.

package/README.md

@@ -3,6 +3,14 @@
 `chem-rx` provides a small atomic state management layer focused on simplicity.
 Useable with or without React!
 
+> **Breaking change (unreleased):** atoms now decide whether to notify
+> subscribers using an equality comparator that **defaults to `Object.is`**.
+> Two behaviors changed: a base atom no longer re-emits when you set an
+> `Object.is`-equal value, and `derive` no longer re-emits when its computed
+> output is `Object.is`-equal (it previously always re-emitted on every parent
+> update). To restore the old always-notify behavior, pass `equals: () => false`.
+> See [Equality & change detection](#equality--change-detection).
+
 ## Atom
 
 `chem-rx` is an atomic approach to state management, similar to
@@ -90,6 +98,14 @@ This can be especially useful for working with different parts of nested Array a
 Atoms created with `select` are **read-only** (`ReadOnlyAtom`). This prevents you from modifying original values that the atom was created from.
 Selected atoms are lazy: calling `value()` reads the latest parent snapshot, and subscribing to a selected atom listens to the parent only while that selected atom has active subscribers.
 
+By default a selected atom notifies subscribers only when the selected value changes by `Object.is`. Pass `{ equals }` to dedup by content instead (see [Equality & change detection](#equality--change-detection)):
+
+```
+const stacy = students.select("stacy", {
+  equals: (a, b) => a?.nickname === b?.nickname,
+});
+```
+
 ```
 const students = Atom({
   stacy: {
@@ -149,19 +165,36 @@ squared$.value()  // "16"
 squared$.set(2)
 ```
 
-You can optionally enforce `readOnly` on an atom at creation time if needed
+By default, a derived atom notifies subscribers only when its computed output changes by `Object.is`. When `deriveFn` returns a fresh object/array each time (so `Object.is` never matches), pass `{ equals }` to dedup by content (see [Equality & change detection](#equality--change-detection)):
+
+```
+const items$ = data$.derive((data) => data.items, {
+  equals: (a, b) => a.length === b.length && a.every((x, i) => x.id === b[i].id),
+});
+```
+
+You can optionally enforce `readOnly` on an atom at creation time if needed. The
+second argument also accepts an options object (`{ readOnly?, equals? }`):
 
 ```
 const atom$ = Atom(3, true);
+// equivalent:
+const atom2$ = Atom(3, { readOnly: true });
 
 // ERR: Property 'set' does not exist on type ReadOnlyAtom
 atom$.set(2)
+
+// content-based dedup on a writable atom
+const point$ = Atom({ x: 0, y: 0 }, { equals: (a, b) => a.x === b.x && a.y === b.y });
 ```
 
 ### Combining Atoms
 
 Multiple atoms can also be **combined** to create brand new atoms.
 
+`combine` produces a fresh array snapshot on every input change, so it re-emits on
+every update. To dedup by content, chain a `derive(fn, { equals })` onto it.
+
 Here's an example of joining a set of normalized data models
 
 ```
@@ -198,8 +231,14 @@ console.log(mary$.select('pets').value())
 
 ### Subscribing to updates
 
-Atoms emit values each time they're updated. You can subscribe callbacks to them
-to act on updates
+Atoms emit values each time they change. You can subscribe callbacks to them
+to act on updates.
+
+Subscribing fires your callback **immediately** with the atom's current value,
+then again on each subsequent change. "Change" is defined by the atom's equality
+comparator, which **defaults to `Object.is`** — so setting an `Object.is`-equal
+value is deduped and will not re-notify (see
+[Equality & change detection](#equality--change-detection)).
 
 ```
 const atom$ = Atom(3);
@@ -207,13 +246,79 @@ const atom$ = Atom(3);
 const subscription = atom$.subscribe(val => {
     console.log("Received value: ", val)
 })
+// immediately logs "Received value: 3"
 
-atom$.set(4)  // "Received value: 4"
+atom$.next(3)  // deduped: Object.is-equal, no log
+atom$.next(4)  // "Received value: 4"
 
 // Unsubscribe to clean up
 subscription.unsubscribe();
 ```
 
+### Equality & change detection
+
+Every atom notifies its subscribers only when its value **changes**, and what
+counts as a "change" is decided by an `equals(previous, next) => boolean`
+comparator. When `equals` returns `true`, the atom still updates `value()` but
+does **not** ping subscribers.
+
+The default comparator for every atom — `Atom`, `derive`, `select`, and
+`combine` — is `Object.is`:
+
+- For primitives (`number`, `string`, `boolean`, ...) that's value equality.
+- For objects and arrays it's **reference identity** — a brand-new object/array
+  is always treated as "changed," even if its contents are identical.
+
+#### Reference vs content equality
+
+Reference identity is the right default, but it breaks down when a producer
+rebuilds fresh objects/arrays on every update (e.g. a game loop that rebuilds
+its whole scene snapshot each tick). Every snapshot is a new reference, so
+`Object.is` reports "changed" every tick and subscribers fire constantly even
+when nothing meaningful changed.
+
+Supply a **content** comparator to fix this:
+
+```
+const tickets$ = frame$.derive(selectTickets, {
+  equals: (a, b) =>
+    a.length === b.length &&
+    a.every((t, i) => t.id === b[i].id && t.status === b[i].status),
+});
+// re-emits only when ticket content actually changes
+```
+
+#### Where you can pass `equals`
+
+```
+Atom(value, { equals })          // base atoms
+parent.derive(fn, { equals })    // derived atoms
+parent.select(key, { equals })   // selected atoms
+```
+
+To force the old "notify on every update" behavior, pass `equals: () => false`.
+
+#### You supply the comparator
+
+`chem-rx` intentionally ships **no** `shallowEqual`/`deepEqual` helpers. A
+generic shallow equal won't reach into nested or rebuilt structures (the tickets
+example above would still see new element references), and a generic deep equal
+is a correctness trap (`NaN`, `Date`, `Map`/`Set`, cycles, ...). Write the cheap
+field comparison your data actually needs, or stamp a revision/version number on
+the data and compare that.
+
+#### React and beyond
+
+Because equality lives on the atom (not in a React hook), content dedup benefits
+**every** subscriber — React components, effects, and other derived atoms alike,
+not just renders. React's `useSyncExternalStore` already bails out on
+`Object.is`-equal snapshots; an atom-level `equals` is what gives you the
+additional **content** dedup.
+
+> Advanced tip: a memoizing selector that returns the _previous_ reference when
+> the content is equal restores referential stability, so all downstream
+> consumers can dedup off plain `Object.is` after a single comparison.
+
 ### Signals
 
 Sometimes, all you want is something to ping you when there's an update. Signals
@@ -284,25 +389,44 @@ function Counter() {
 
 Remember that you can mix and match for any of your needs
 
-### useSelectAtom
+### useSelector
 
-With `useSelectAtom` you can select a specific key from an atom, and still have it live
-update in your react component.
+With `useSelector` you can derive any value from an atom with a selector function, and
+have your component live update — re-rendering only when the selected value changes.
 
 ```
 import { Atom } from 'chem-rx'
-import { useSelectAtom } from 'chem-rx/react'
+import { useSelector } from 'chem-rx/react'
 
 const count$ = Atom({ inner: 0 })
 
 function Counter() {
-  const count = useSelectAtom(count$, 'inner')
+  const count = useSelector(count$, (s) => s.inner)
   return (
     <h1>
       {count}
         <button onClick={() => count$.set('inner', count + 2)}>one up</button> ...
 ```
 
+`useSelector` takes an optional `equals` comparator (defaulting to `Object.is`) so you
+can dedupe re-renders by content. This is the React-side counterpart to the atom-level
+`equals` option described in [Equality & change detection](#equality--change-detection):
+even if the parent atom rebuilds its value (and references) on every update, the
+component only re-renders when the selected slice is *not* equal.
+
+```
+const frame$ = Atom(initialFrame)
+
+const itemsEqual = (a, b) =>
+  a.length === b.length && a.every((v, i) => v === b[i])
+
+function ItemList() {
+  // re-renders only when `items` changes by content, not every frame
+  const items = useSelector(frame$, (f) => f.items, itemsEqual)
+  return <ul>{items.map((it) => <li key={it.id}>{it.label}</li>)}</ul>
+}
+```
+
 ### hydrateAtoms
 
 With SSR, your atoms will likely need to be properly hydrated to prevent

package/dist/Atom.d.ts

@@ -5,10 +5,21 @@ export type AtomTuple<T> = {
 type SelectedValue<T, K extends keyof T> = T extends readonly (infer W)[] ? W : T[K];
 type SelectKey<T> = keyof NonNullable<T>;
 type SelectValue<T, K extends SelectKey<T>> = Extract<T, null | undefined> extends never ? SelectedValue<NonNullable<T>, K> : SelectedValue<NonNullable<T>, K> | undefined;
+/**
+ * Comparator used to decide whether an atom's value has changed.
+ *
+ * An atom notifies subscribers only when `equals(previous, next)` returns
+ * `false`. The default for every atom is {@link Object.is} (value equality for
+ * primitives, reference identity for objects/arrays). Supply a content
+ * comparator to dedup by data, or `() => false` to force every update to emit.
+ */
+export type Equals<T> = (previousValue: T, nextValue: T) => boolean;
+type AtomOptions<T> = {
+    equals?: Equals<T>;
+};
 type AtomDependency<T> = {
     getSnapshot: (force?: boolean) => T;
     subscribe: (onDependencyChange: () => void) => AtomSubscription | (() => void) | void;
-    shouldNotify?: (previousValue: T, nextValue: T) => boolean;
 };
 export declare class ReadOnlyAtom<T> {
     private _store;
@@ -16,13 +27,34 @@ export declare class ReadOnlyAtom<T> {
     private _dependency;
     private _dependencySubscription;
     private _subscriberCount;
-    constructor(_value: T | AtomSource<T>, dependency?: AtomDependency<T>);
-    derive<A>(deriveFn: (value: T, index: number) => A): ReadOnlyAtom<A>;
+    private _equals;
+    /**
+     * @param options.equals Comparator deciding when the value has changed.
+     *   Defaults to {@link Object.is}. Subscribers are notified only when it
+     *   returns `false`.
+     */
+    constructor(_value: T | AtomSource<T>, dependency?: AtomDependency<T>, options?: AtomOptions<T>);
+    /**
+     * Create a read-only atom whose value is derived from this atom.
+     *
+     * By default the derived atom notifies subscribers only when its computed
+     * output differs by {@link Object.is}. Pass `options.equals` to dedup by
+     * content (useful when `deriveFn` returns a fresh object/array each time), or
+     * `equals: () => false` to re-emit on every parent update.
+     */
+    derive<A>(deriveFn: (value: T, index: number) => A, options?: AtomOptions<A>): ReadOnlyAtom<A>;
     subscribe(observer: AtomObserver<T>): AtomSubscription;
     value(): T;
     dispose(): void;
     get<K extends SelectKey<T>>(key: K): SelectValue<T, K>;
-    select<K extends SelectKey<T>>(key: K): ReadOnlyAtom<SelectValue<T, K>>;
+    /**
+     * Create a read-only atom that tracks `key` on this atom's value.
+     *
+     * By default the selected atom notifies subscribers only when the selected
+     * value differs by {@link Object.is}. Pass `options.equals` to dedup by
+     * content instead.
+     */
+    select<K extends SelectKey<T>>(key: K, options?: AtomOptions<SelectValue<T, K>>): ReadOnlyAtom<SelectValue<T, K>>;
     private _refresh;
     private _retainDependency;
     private _releaseDependency;
@@ -40,27 +72,38 @@ export declare class BaseAtom<T> extends ReadOnlyAtom<T> {
     set<K extends SelectKey<T>>(nextKey: K, nextValue: NonNullable<T>[K]): void;
 }
 export declare class NullableBaseAtom<T> extends BaseAtom<T | null | undefined> {
-    constructor(_value?: T | null | undefined | AtomSource<T | null | undefined>);
+    constructor(_value?: T | null | undefined | AtomSource<T | null | undefined>, options?: AtomOptions<T | null | undefined>);
     next(nextVal: T | null | undefined): void;
     reset(): void;
 }
 export declare class ArrayAtom<T> extends BaseAtom<T[]> {
-    constructor(initialValue?: T[] | AtomSource<T[]>);
+    constructor(initialValue?: T[] | AtomSource<T[]>, options?: AtomOptions<T[]>);
     push(nextVal: T): void;
 }
+/**
+ * Options for the {@link Atom} factory. `readOnly` produces a
+ * {@link ReadOnlyAtom}; `equals` sets the change comparator (defaults to
+ * {@link Object.is}).
+ */
+export type AtomFactoryOptions<T> = AtomOptions<T> & {
+    readOnly?: boolean;
+};
 export declare function Atom<T>(value: T | AtomSource<T>, readOnly: true): ReadOnlyAtom<T>;
-export declare function Atom<T extends any[]>(value: AtomSource<T>): ArrayAtom<T[number]>;
-export declare function Atom<T>(value: AtomSource<T>): BaseAtom<T>;
-export declare function Atom<T extends any[]>(value?: T): ArrayAtom<T[number]>;
+export declare function Atom<T>(value: T | AtomSource<T>, options: AtomFactoryOptions<T> & {
+    readOnly: true;
+}): ReadOnlyAtom<T>;
+export declare function Atom<T extends any[]>(value: AtomSource<T>, options?: AtomFactoryOptions<T>): ArrayAtom<T[number]>;
+export declare function Atom<T>(value: AtomSource<T>, options?: AtomFactoryOptions<T>): BaseAtom<T>;
+export declare function Atom<T extends any[]>(value: T, options?: AtomFactoryOptions<T>): ArrayAtom<T[number]>;
 export declare function Atom<T extends {
     [key: string]: T[keyof T];
-}>(value: T): BaseAtom<T>;
+}>(value: T, options?: AtomFactoryOptions<T>): BaseAtom<T>;
 export declare function Atom<T extends {
     [key: string]: T[keyof T];
-}>(value?: T): NullableBaseAtom<T>;
-export declare function Atom<T>(value: T): BaseAtom<T>;
-export declare function Atom<T>(value?: T): NullableBaseAtom<T>;
-export declare function Atom<T>(value: T | AtomSource<T>, readOnly?: boolean): ReadOnlyAtom<T> | BaseAtom<T>;
+}>(value?: T, options?: AtomFactoryOptions<T>): NullableBaseAtom<T>;
+export declare function Atom<T>(value: T, options?: AtomFactoryOptions<T>): BaseAtom<T>;
+export declare function Atom<T>(value?: T, options?: AtomFactoryOptions<T>): NullableBaseAtom<T>;
+export declare function Atom<T>(value: T | AtomSource<T>, optionsOrReadOnly?: boolean | AtomFactoryOptions<T>): ReadOnlyAtom<T> | BaseAtom<T>;
 export declare namespace Atom {
     var combine: <A extends readonly unknown[]>(...atoms: AtomTuple<A>) => ReadOnlyAtom<A>;
 }

package/dist/Atom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Atom.d.ts","sourceRoot":"","sources":["../src/Atom.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Atom.d.ts","sourceRoot":"","sources":["../src/Atom.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs.js

@@ -149,13 +149,29 @@ var ValueStore = /*#__PURE__*/function () {
   return ValueStore;
 }();
 
+/**
+ * Comparator used to decide whether an atom's value has changed.
+ *
+ * An atom notifies subscribers only when `equals(previous, next)` returns
+ * `false`. The default for every atom is {@link Object.is} (value equality for
+ * primitives, reference identity for objects/arrays). Supply a content
+ * comparator to dedup by data, or `() => false` to force every update to emit.
+ */
+
 var ReadOnlyAtom = /*#__PURE__*/function () {
-  function ReadOnlyAtom(_value, dependency) {
-    var _this = this;
+  /**
+   * @param options.equals Comparator deciding when the value has changed.
+   *   Defaults to {@link Object.is}. Subscribers are notified only when it
+   *   returns `false`.
+   */
+  function ReadOnlyAtom(_value, dependency, options) {
+    var _options$equals,
+      _this = this;
     this._subscriptions = [];
     this._dependency = null;
     this._dependencySubscription = null;
     this._subscriberCount = 0;
+    this._equals = (_options$equals = options == null ? void 0 : options.equals) != null ? _options$equals : Object.is;
     if (dependency) {
       this._dependency = dependency;
       this._store = new ValueStore(_value);
@@ -168,8 +184,17 @@ var ReadOnlyAtom = /*#__PURE__*/function () {
       this._store = new ValueStore(_value);
     }
   }
+
+  /**
+   * Create a read-only atom whose value is derived from this atom.
+   *
+   * By default the derived atom notifies subscribers only when its computed
+   * output differs by {@link Object.is}. Pass `options.equals` to dedup by
+   * content (useful when `deriveFn` returns a fresh object/array each time), or
+   * `equals: () => false` to re-emit on every parent update.
+   */
   var _proto = ReadOnlyAtom.prototype;
-  _proto.derive = function derive(deriveFn) {
+  _proto.derive = function derive(deriveFn, options) {
     var _this2 = this;
     var index = 0;
     var hasCachedInput = false;
@@ -193,11 +218,8 @@ var ReadOnlyAtom = /*#__PURE__*/function () {
         return _this2._subscribe(onDependencyChange, {
           emitImmediately: false
         });
-      },
-      shouldNotify: function shouldNotify() {
-        return true;
       }
-    });
+    }, options);
   };
   _proto.subscribe = function subscribe(observer) {
     return this._subscribe(observer);
@@ -221,8 +243,16 @@ var ReadOnlyAtom = /*#__PURE__*/function () {
   _proto.get = function get(key) {
     var val = this.value();
     return val == null ? void 0 : val[key];
-  };
-  _proto.select = function select(key) {
+  }
+
+  /**
+   * Create a read-only atom that tracks `key` on this atom's value.
+   *
+   * By default the selected atom notifies subscribers only when the selected
+   * value differs by {@link Object.is}. Pass `options.equals` to dedup by
+   * content instead.
+   */;
+  _proto.select = function select(key, options) {
     var _this3 = this;
     var getSnapshot = function getSnapshot() {
       var value = _this3.value();
@@ -235,10 +265,9 @@ var ReadOnlyAtom = /*#__PURE__*/function () {
           emitImmediately: false
         });
       }
-    });
+    }, options);
   };
   _proto._refresh = function _refresh(emit, force) {
-    var _this$_dependency$sho, _this$_dependency$sho2, _this$_dependency;
     if (force === void 0) {
       force = false;
     }
@@ -247,7 +276,7 @@ var ReadOnlyAtom = /*#__PURE__*/function () {
     }
     var previousValue = this._store.getValue();
     var nextValue = this._dependency.getSnapshot(force);
-    var shouldNotify = emit && ((_this$_dependency$sho = (_this$_dependency$sho2 = (_this$_dependency = this._dependency).shouldNotify) == null ? void 0 : _this$_dependency$sho2.call(_this$_dependency, previousValue, nextValue)) != null ? _this$_dependency$sho : !Object.is(previousValue, nextValue));
+    var shouldNotify = emit && !this._equals(previousValue, nextValue);
     if (shouldNotify) {
       this._store.next(nextValue);
     } else {
@@ -281,7 +310,12 @@ var ReadOnlyAtom = /*#__PURE__*/function () {
 
   /** @internal */;
   _proto._next = function _next(value) {
-    this._store.next(value);
+    var previousValue = this._store.getValue();
+    if (this._equals(previousValue, value)) {
+      this._store.setValue(value);
+    } else {
+      this._store.next(value);
+    }
   }
 
   /** @internal */;
@@ -333,8 +367,8 @@ var BaseAtom = /*#__PURE__*/function (_ReadOnlyAtom2) {
   return BaseAtom;
 }(ReadOnlyAtom);
 var NullableBaseAtom = /*#__PURE__*/function (_BaseAtom) {
-  function NullableBaseAtom(_value) {
-    return _BaseAtom.call(this, _value) || this;
+  function NullableBaseAtom(_value, options) {
+    return _BaseAtom.call(this, _value, undefined, options) || this;
   }
   _inheritsLoose(NullableBaseAtom, _BaseAtom);
   var _proto3 = NullableBaseAtom.prototype;
@@ -347,12 +381,12 @@ var NullableBaseAtom = /*#__PURE__*/function (_BaseAtom) {
   return NullableBaseAtom;
 }(BaseAtom);
 var ArrayAtom = /*#__PURE__*/function (_BaseAtom2) {
-  function ArrayAtom(initialValue) {
+  function ArrayAtom(initialValue, options) {
     var _this6;
     if (initialValue === undefined) {
-      _this6 = _BaseAtom2.call(this, []) || this;
+      _this6 = _BaseAtom2.call(this, [], undefined, options) || this;
     } else {
-      _this6 = _BaseAtom2.call(this, initialValue) || this;
+      _this6 = _BaseAtom2.call(this, initialValue, undefined, options) || this;
     }
     return _assertThisInitialized(_this6);
   }
@@ -363,27 +397,44 @@ var ArrayAtom = /*#__PURE__*/function (_BaseAtom2) {
   };
   return ArrayAtom;
 }(BaseAtom);
-function Atom(_value, readOnly) {
-  if (readOnly === void 0) {
-    readOnly = false;
-  }
+
+/**
+ * Options for the {@link Atom} factory. `readOnly` produces a
+ * {@link ReadOnlyAtom}; `equals` sets the change comparator (defaults to
+ * {@link Object.is}).
+ */
+
+// Legacy positional `readOnly` form.
+
+// Options-object form.
+
+function Atom(_value, optionsOrReadOnly) {
+  var factoryOptions = typeof optionsOrReadOnly === "boolean" ? {
+    readOnly: optionsOrReadOnly
+  } : optionsOrReadOnly != null ? optionsOrReadOnly : {};
+  var _factoryOptions$readO = factoryOptions.readOnly,
+    readOnly = _factoryOptions$readO === void 0 ? false : _factoryOptions$readO,
+    equals = factoryOptions.equals;
+  var atomOptions = equals ? {
+    equals: equals
+  } : undefined;
   if (readOnly) {
-    return new ReadOnlyAtom(_value);
+    return new ReadOnlyAtom(_value, undefined, atomOptions);
   }
   if (isAtomSource(_value)) {
     var sourceValue = readAtomSourceValue(_value);
     if (Array.isArray(sourceValue)) {
-      return new ArrayAtom(_value);
+      return new ArrayAtom(_value, atomOptions);
     }
-    return new BaseAtom(_value);
+    return new BaseAtom(_value, undefined, atomOptions);
   }
   if (Array.isArray(_value)) {
-    return new ArrayAtom(_value);
+    return new ArrayAtom(_value, atomOptions);
   }
   if (_value == null) {
-    return new NullableBaseAtom();
+    return new NullableBaseAtom(undefined, atomOptions);
   }
-  return new BaseAtom(_value);
+  return new BaseAtom(_value, undefined, atomOptions);
 }
 Atom.combine = function () {
   for (var _len = arguments.length, atoms = new Array(_len), _key = 0; _key < _len; _key++) {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { Atom } from "./Atom";
+export type { Equals, AtomFactoryOptions } from "./Atom";
 export { hydrateAtoms } from "./useHydrateAtoms";
 export { Signal } from "./Signal";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.iife.js

@@ -150,13 +150,29 @@ var chemicalRx = (function (exports) {
     return ValueStore;
   }();
 
+  /**
+   * Comparator used to decide whether an atom's value has changed.
+   *
+   * An atom notifies subscribers only when `equals(previous, next)` returns
+   * `false`. The default for every atom is {@link Object.is} (value equality for
+   * primitives, reference identity for objects/arrays). Supply a content
+   * comparator to dedup by data, or `() => false` to force every update to emit.
+   */
+
   var ReadOnlyAtom = /*#__PURE__*/function () {
-    function ReadOnlyAtom(_value, dependency) {
-      var _this = this;
+    /**
+     * @param options.equals Comparator deciding when the value has changed.
+     *   Defaults to {@link Object.is}. Subscribers are notified only when it
+     *   returns `false`.
+     */
+    function ReadOnlyAtom(_value, dependency, options) {
+      var _options$equals,
+        _this = this;
       this._subscriptions = [];
       this._dependency = null;
       this._dependencySubscription = null;
       this._subscriberCount = 0;
+      this._equals = (_options$equals = options == null ? void 0 : options.equals) != null ? _options$equals : Object.is;
       if (dependency) {
         this._dependency = dependency;
         this._store = new ValueStore(_value);
@@ -169,8 +185,17 @@ var chemicalRx = (function (exports) {
         this._store = new ValueStore(_value);
       }
     }
+
+    /**
+     * Create a read-only atom whose value is derived from this atom.
+     *
+     * By default the derived atom notifies subscribers only when its computed
+     * output differs by {@link Object.is}. Pass `options.equals` to dedup by
+     * content (useful when `deriveFn` returns a fresh object/array each time), or
+     * `equals: () => false` to re-emit on every parent update.
+     */
     var _proto = ReadOnlyAtom.prototype;
-    _proto.derive = function derive(deriveFn) {
+    _proto.derive = function derive(deriveFn, options) {
       var _this2 = this;
       var index = 0;
       var hasCachedInput = false;
@@ -194,11 +219,8 @@ var chemicalRx = (function (exports) {
           return _this2._subscribe(onDependencyChange, {
             emitImmediately: false
           });
-        },
-        shouldNotify: function shouldNotify() {
-          return true;
         }
-      });
+      }, options);
     };
     _proto.subscribe = function subscribe(observer) {
       return this._subscribe(observer);
@@ -222,8 +244,16 @@ var chemicalRx = (function (exports) {
     _proto.get = function get(key) {
       var val = this.value();
       return val == null ? void 0 : val[key];
-    };
-    _proto.select = function select(key) {
+    }
+
+    /**
+     * Create a read-only atom that tracks `key` on this atom's value.
+     *
+     * By default the selected atom notifies subscribers only when the selected
+     * value differs by {@link Object.is}. Pass `options.equals` to dedup by
+     * content instead.
+     */;
+    _proto.select = function select(key, options) {
       var _this3 = this;
       var getSnapshot = function getSnapshot() {
         var value = _this3.value();
@@ -236,10 +266,9 @@ var chemicalRx = (function (exports) {
             emitImmediately: false
           });
         }
-      });
+      }, options);
     };
     _proto._refresh = function _refresh(emit, force) {
-      var _this$_dependency$sho, _this$_dependency$sho2, _this$_dependency;
       if (force === void 0) {
         force = false;
       }
@@ -248,7 +277,7 @@ var chemicalRx = (function (exports) {
       }
       var previousValue = this._store.getValue();
       var nextValue = this._dependency.getSnapshot(force);
-      var shouldNotify = emit && ((_this$_dependency$sho = (_this$_dependency$sho2 = (_this$_dependency = this._dependency).shouldNotify) == null ? void 0 : _this$_dependency$sho2.call(_this$_dependency, previousValue, nextValue)) != null ? _this$_dependency$sho : !Object.is(previousValue, nextValue));
+      var shouldNotify = emit && !this._equals(previousValue, nextValue);
       if (shouldNotify) {
         this._store.next(nextValue);
       } else {
@@ -282,7 +311,12 @@ var chemicalRx = (function (exports) {
 
     /** @internal */;
     _proto._next = function _next(value) {
-      this._store.next(value);
+      var previousValue = this._store.getValue();
+      if (this._equals(previousValue, value)) {
+        this._store.setValue(value);
+      } else {
+        this._store.next(value);
+      }
     }
 
     /** @internal */;
@@ -334,8 +368,8 @@ var chemicalRx = (function (exports) {
     return BaseAtom;
   }(ReadOnlyAtom);
   var NullableBaseAtom = /*#__PURE__*/function (_BaseAtom) {
-    function NullableBaseAtom(_value) {
-      return _BaseAtom.call(this, _value) || this;
+    function NullableBaseAtom(_value, options) {
+      return _BaseAtom.call(this, _value, undefined, options) || this;
     }
     _inheritsLoose(NullableBaseAtom, _BaseAtom);
     var _proto3 = NullableBaseAtom.prototype;
@@ -348,12 +382,12 @@ var chemicalRx = (function (exports) {
     return NullableBaseAtom;
   }(BaseAtom);
   var ArrayAtom = /*#__PURE__*/function (_BaseAtom2) {
-    function ArrayAtom(initialValue) {
+    function ArrayAtom(initialValue, options) {
       var _this6;
       if (initialValue === undefined) {
-        _this6 = _BaseAtom2.call(this, []) || this;
+        _this6 = _BaseAtom2.call(this, [], undefined, options) || this;
       } else {
-        _this6 = _BaseAtom2.call(this, initialValue) || this;
+        _this6 = _BaseAtom2.call(this, initialValue, undefined, options) || this;
       }
       return _assertThisInitialized(_this6);
     }
@@ -364,27 +398,44 @@ var chemicalRx = (function (exports) {
     };
     return ArrayAtom;
   }(BaseAtom);
-  function Atom(_value, readOnly) {
-    if (readOnly === void 0) {
-      readOnly = false;
-    }
+
+  /**
+   * Options for the {@link Atom} factory. `readOnly` produces a
+   * {@link ReadOnlyAtom}; `equals` sets the change comparator (defaults to
+   * {@link Object.is}).
+   */
+
+  // Legacy positional `readOnly` form.
+
+  // Options-object form.
+
+  function Atom(_value, optionsOrReadOnly) {
+    var factoryOptions = typeof optionsOrReadOnly === "boolean" ? {
+      readOnly: optionsOrReadOnly
+    } : optionsOrReadOnly != null ? optionsOrReadOnly : {};
+    var _factoryOptions$readO = factoryOptions.readOnly,
+      readOnly = _factoryOptions$readO === void 0 ? false : _factoryOptions$readO,
+      equals = factoryOptions.equals;
+    var atomOptions = equals ? {
+      equals: equals
+    } : undefined;
     if (readOnly) {
-      return new ReadOnlyAtom(_value);
+      return new ReadOnlyAtom(_value, undefined, atomOptions);
     }
     if (isAtomSource(_value)) {
       var sourceValue = readAtomSourceValue(_value);
       if (Array.isArray(sourceValue)) {
-        return new ArrayAtom(_value);
+        return new ArrayAtom(_value, atomOptions);
       }
-      return new BaseAtom(_value);
+      return new BaseAtom(_value, undefined, atomOptions);
     }
     if (Array.isArray(_value)) {
-      return new ArrayAtom(_value);
+      return new ArrayAtom(_value, atomOptions);
     }
     if (_value == null) {
-      return new NullableBaseAtom();
+      return new NullableBaseAtom(undefined, atomOptions);
     }
-    return new BaseAtom(_value);
+    return new BaseAtom(_value, undefined, atomOptions);
   }
   Atom.combine = function () {
     for (var _len = arguments.length, atoms = new Array(_len), _key = 0; _key < _len; _key++) {

package/dist/index.mjs

@@ -95,12 +95,28 @@ class ValueStore {
   }
 }
 
+/**
+ * Comparator used to decide whether an atom's value has changed.
+ *
+ * An atom notifies subscribers only when `equals(previous, next)` returns
+ * `false`. The default for every atom is {@link Object.is} (value equality for
+ * primitives, reference identity for objects/arrays). Supply a content
+ * comparator to dedup by data, or `() => false` to force every update to emit.
+ */
+
 class ReadOnlyAtom {
-  constructor(_value, dependency) {
+  /**
+   * @param options.equals Comparator deciding when the value has changed.
+   *   Defaults to {@link Object.is}. Subscribers are notified only when it
+   *   returns `false`.
+   */
+  constructor(_value, dependency, options) {
+    var _options$equals;
     this._subscriptions = [];
     this._dependency = null;
     this._dependencySubscription = null;
     this._subscriberCount = 0;
+    this._equals = (_options$equals = options == null ? void 0 : options.equals) != null ? _options$equals : Object.is;
     if (dependency) {
       this._dependency = dependency;
       this._store = new ValueStore(_value);
@@ -113,7 +129,16 @@ class ReadOnlyAtom {
       this._store = new ValueStore(_value);
     }
   }
-  derive(deriveFn) {
+
+  /**
+   * Create a read-only atom whose value is derived from this atom.
+   *
+   * By default the derived atom notifies subscribers only when its computed
+   * output differs by {@link Object.is}. Pass `options.equals` to dedup by
+   * content (useful when `deriveFn` returns a fresh object/array each time), or
+   * `equals: () => false` to re-emit on every parent update.
+   */
+  derive(deriveFn, options) {
     let index = 0;
     let hasCachedInput = false;
     let cachedInput;
@@ -131,9 +156,8 @@ class ReadOnlyAtom {
       getSnapshot,
       subscribe: onDependencyChange => this._subscribe(onDependencyChange, {
         emitImmediately: false
-      }),
-      shouldNotify: () => true
-    });
+      })
+    }, options);
   }
   subscribe(observer) {
     return this._subscribe(observer);
@@ -157,7 +181,15 @@ class ReadOnlyAtom {
     const val = this.value();
     return val == null ? void 0 : val[key];
   }
-  select(key) {
+
+  /**
+   * Create a read-only atom that tracks `key` on this atom's value.
+   *
+   * By default the selected atom notifies subscribers only when the selected
+   * value differs by {@link Object.is}. Pass `options.equals` to dedup by
+   * content instead.
+   */
+  select(key, options) {
     const getSnapshot = () => {
       const value = this.value();
       return value == null ? void 0 : value[key];
@@ -167,16 +199,15 @@ class ReadOnlyAtom {
       subscribe: onDependencyChange => this._subscribe(onDependencyChange, {
         emitImmediately: false
       })
-    });
+    }, options);
   }
   _refresh(emit, force = false) {
-    var _this$_dependency$sho, _this$_dependency$sho2, _this$_dependency;
     if (!this._dependency) {
       return this._store.getValue();
     }
     const previousValue = this._store.getValue();
     const nextValue = this._dependency.getSnapshot(force);
-    const shouldNotify = emit && ((_this$_dependency$sho = (_this$_dependency$sho2 = (_this$_dependency = this._dependency).shouldNotify) == null ? void 0 : _this$_dependency$sho2.call(_this$_dependency, previousValue, nextValue)) != null ? _this$_dependency$sho : !Object.is(previousValue, nextValue));
+    const shouldNotify = emit && !this._equals(previousValue, nextValue);
     if (shouldNotify) {
       this._store.next(nextValue);
     } else {
@@ -209,7 +240,12 @@ class ReadOnlyAtom {
 
   /** @internal */
   _next(value) {
-    this._store.next(value);
+    const previousValue = this._store.getValue();
+    if (this._equals(previousValue, value)) {
+      this._store.setValue(value);
+    } else {
+      this._store.next(value);
+    }
   }
 
   /** @internal */
@@ -254,8 +290,8 @@ class BaseAtom extends ReadOnlyAtom {
   }
 }
 class NullableBaseAtom extends BaseAtom {
-  constructor(_value) {
-    super(_value);
+  constructor(_value, options) {
+    super(_value, undefined, options);
   }
   next(nextVal) {
     this._next(nextVal);
@@ -265,35 +301,56 @@ class NullableBaseAtom extends BaseAtom {
   }
 }
 class ArrayAtom extends BaseAtom {
-  constructor(initialValue) {
+  constructor(initialValue, options) {
     if (initialValue === undefined) {
-      super([]);
+      super([], undefined, options);
     } else {
-      super(initialValue);
+      super(initialValue, undefined, options);
     }
   }
   push(nextVal) {
     this._next([...this.value(), nextVal]);
   }
 }
-function Atom(_value, readOnly = false) {
+
+/**
+ * Options for the {@link Atom} factory. `readOnly` produces a
+ * {@link ReadOnlyAtom}; `equals` sets the change comparator (defaults to
+ * {@link Object.is}).
+ */
+
+// Legacy positional `readOnly` form.
+
+// Options-object form.
+
+function Atom(_value, optionsOrReadOnly) {
+  const factoryOptions = typeof optionsOrReadOnly === "boolean" ? {
+    readOnly: optionsOrReadOnly
+  } : optionsOrReadOnly != null ? optionsOrReadOnly : {};
+  const {
+    readOnly = false,
+    equals
+  } = factoryOptions;
+  const atomOptions = equals ? {
+    equals
+  } : undefined;
   if (readOnly) {
-    return new ReadOnlyAtom(_value);
+    return new ReadOnlyAtom(_value, undefined, atomOptions);
   }
   if (isAtomSource(_value)) {
     const sourceValue = readAtomSourceValue(_value);
     if (Array.isArray(sourceValue)) {
-      return new ArrayAtom(_value);
+      return new ArrayAtom(_value, atomOptions);
     }
-    return new BaseAtom(_value);
+    return new BaseAtom(_value, undefined, atomOptions);
   }
   if (Array.isArray(_value)) {
-    return new ArrayAtom(_value);
+    return new ArrayAtom(_value, atomOptions);
   }
   if (_value == null) {
-    return new NullableBaseAtom();
+    return new NullableBaseAtom(undefined, atomOptions);
   }
-  return new BaseAtom(_value);
+  return new BaseAtom(_value, undefined, atomOptions);
 }
 Atom.combine = (...atoms) => {
   const getSnapshot = () => atoms.map(atom => atom.value());

package/dist/react.cjs.js

@@ -38,13 +38,57 @@ function useSignal(signal, callback, id) {
   }, [signal, callback, id]);
 }
 
-function useSelectAtom(atom, key) {
-  var selectedAtom = react.useMemo(function () {
-    return atom.select(key);
-  }, [atom, key]);
-  return useAtom(selectedAtom);
+function createSelectorMemo(selector, equals) {
+  var hasValue = false;
+  var prevSnapshot;
+  var prevSelection;
+  return function (snapshot) {
+    if (hasValue && Object.is(prevSnapshot, snapshot)) {
+      return prevSelection;
+    }
+    var next = selector(snapshot);
+    if (hasValue && equals(prevSelection, next)) {
+      prevSnapshot = snapshot;
+      return prevSelection;
+    }
+    hasValue = true;
+    prevSnapshot = snapshot;
+    prevSelection = next;
+    return next;
+  };
+}
+
+/**
+ * Subscribe to a slice of an atom, re-rendering only when the selected value
+ * changes. The optional `equals` comparator dedupes by content (defaults to
+ * `Object.is`), so a parent atom that churns references every update will not
+ * re-render the component when the selected slice is content-equal.
+ */
+function useSelector(atom, selector, equals) {
+  if (equals === void 0) {
+    equals = Object.is;
+  }
+  var select = react.useMemo(function () {
+    return createSelectorMemo(selector, equals);
+  }, [selector, equals]);
+  return react.useSyncExternalStore(function (onStoreChange) {
+    var subscribed = false;
+    var subscription = atom.subscribe(function () {
+      if (subscribed) {
+        onStoreChange();
+      }
+    });
+    subscribed = true;
+    return function () {
+      subscription.unsubscribe();
+    };
+  }, function () {
+    return select(atom.value());
+  }, function () {
+    return select(atom.value());
+  });
 }
 
 exports.useAtom = useAtom;
-exports.useSelectAtom = useSelectAtom;
+exports.useSelector = useSelector;
 exports.useSignal = useSignal;

package/dist/react.d.ts

@@ -1,4 +1,4 @@
 export { useAtom } from "./useAtom";
 export { useSignal } from "./useSignal";
-export { useSelectAtom } from "./useSelectAtom";
+export { useSelector } from "./useSelector";
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/react.mjs

@@ -32,9 +32,46 @@ function useSignal(signal, callback, id) {
   }, [signal, callback, id]);
 }
 
-function useSelectAtom(atom, key) {
-  const selectedAtom = useMemo(() => atom.select(key), [atom, key]);
-  return useAtom(selectedAtom);
+function createSelectorMemo(selector, equals) {
+  let hasValue = false;
+  let prevSnapshot;
+  let prevSelection;
+  return snapshot => {
+    if (hasValue && Object.is(prevSnapshot, snapshot)) {
+      return prevSelection;
+    }
+    const next = selector(snapshot);
+    if (hasValue && equals(prevSelection, next)) {
+      prevSnapshot = snapshot;
+      return prevSelection;
+    }
+    hasValue = true;
+    prevSnapshot = snapshot;
+    prevSelection = next;
+    return next;
+  };
+}
+
+/**
+ * Subscribe to a slice of an atom, re-rendering only when the selected value
+ * changes. The optional `equals` comparator dedupes by content (defaults to
+ * `Object.is`), so a parent atom that churns references every update will not
+ * re-render the component when the selected slice is content-equal.
+ */
+function useSelector(atom, selector, equals = Object.is) {
+  const select = useMemo(() => createSelectorMemo(selector, equals), [selector, equals]);
+  return useSyncExternalStore(onStoreChange => {
+    let subscribed = false;
+    const subscription = atom.subscribe(() => {
+      if (subscribed) {
+        onStoreChange();
+      }
+    });
+    subscribed = true;
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, () => select(atom.value()), () => select(atom.value()));
 }
 
-export { useAtom, useSelectAtom, useSignal };
+export { useAtom, useSelector, useSignal };

package/dist/useSelector.d.ts

@@ -0,0 +1,10 @@
+import { Equals, ReadOnlyAtom } from "./Atom";
+export declare function createSelectorMemo<T, R>(selector: (value: T) => R, equals: Equals<R>): (snapshot: T) => R;
+/**
+ * Subscribe to a slice of an atom, re-rendering only when the selected value
+ * changes. The optional `equals` comparator dedupes by content (defaults to
+ * `Object.is`), so a parent atom that churns references every update will not
+ * re-render the component when the selected slice is content-equal.
+ */
+export declare function useSelector<T, R>(atom: ReadOnlyAtom<T>, selector: (value: T) => R, equals?: Equals<R>): R;
+//# sourceMappingURL=useSelector.d.ts.map

package/dist/useSelector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSelector.d.ts","sourceRoot":"","sources":["../src/useSelector.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAE9C,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EACrC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EACzB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAChB,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAkBpB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAC9B,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EACrB,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EACzB,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAC5B,CAAC,CAqBH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chem-rx",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "react state primitives with framework-agnostic atoms",
   "main": "dist/index.cjs.js",
   "module": "dist/index.mjs",
@@ -8,6 +8,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
@@ -15,7 +16,7 @@
     "test": "jest",
     "clean": "rm -rf ./dist",
     "build": "pnpm run prebuild && tsc --emitDeclarationOnly && rollup -c",
-    "bump": "pnpm run build && pnpm version patch"
+    "prepublishOnly": "pnpm run test && pnpm run build"
   },
   "repository": {
     "type": "git",
@@ -35,9 +36,14 @@
     "@babel/preset-typescript": "^7.22.5",
     "@rollup/plugin-babel": "^6.0.3",
     "@rollup/plugin-node-resolve": "^15.1.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/jest": "^29.5.3",
     "@types/react": "^18.2.20",
     "jest": "^29.6.2",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "rimraf": "^5.0.1",
     "rollup": "^3.28.0",
     "rollup-plugin-size-snapshot": "^0.12.0",

package/dist/useSelectAtom.d.ts

@@ -1,5 +0,0 @@
-import { BaseAtom, NullableBaseAtom, ReadOnlyAtom } from "./Atom";
-export declare function useSelectAtom<T extends {
-    [key in K]: V;
-}, K extends keyof T, V = T[K]>(atom: NullableBaseAtom<T> | BaseAtom<T> | ReadOnlyAtom<T>, key: K): T[K];
-//# sourceMappingURL=useSelectAtom.d.ts.map

package/dist/useSelectAtom.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useSelectAtom.d.ts","sourceRoot":"","sources":["../src/useSelectAtom.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGlE,wBAAgB,aAAa,CAC3B,CAAC,SACG;KACG,GAAG,IAAI,CAAC,GAAG,CAAC;CACd,EACL,CAAC,SAAS,MAAM,CAAC,EACjB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EACR,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAMzE"}