@aihu/reactive 0.2.0

package/README.md

@@ -0,0 +1,145 @@
+# @aihu/reactive
+
+> **Aihu** — agentic discovery and interaction, for human purpose.
+
+Fine-grained Proxy-backed deep reactive trees on aihu signals — lazy per-(object,key) tracking nodes, plain-assignment writes, mutate/reconcile.
+
+
+<!-- BEGIN_HANDWRITTEN: prose -->
+Design: [`docs/plans/2026-07-24-deep-reactivity.md`](../../docs/plans/2026-07-24-deep-reactivity.md).
+
+A Solid-shaped node model (lazily allocated per-`(object, key)` tracking cells,
+allocated on first proxy touch — tracked or not) with Vue-shaped write
+ergonomics (plain `obj.key = value` assignment, no `setStore(...)` path
+tuples). Built entirely on the public `@aihu/signals` API — `@aihu/signals`
+is `external`, so this package adds **zero bytes** to the signals core row.
+
+```ts
+import { reactive, mutate, unwrap } from '@aihu/reactive'
+import { computed, effect } from '@aihu/signals'
+
+const user = reactive({ name: 'Ada', address: { city: 'London' }, tags: ['math'] })
+
+effect(() => console.log(user.address.city)) // tracks node(user,'address') + node(addr,'city')
+
+user.address.city = 'Cambridge' // one flush → logs
+
+mutate(user, (u) => {
+  // ONE flush for three writes
+  u.name = 'Ada L.'
+  u.address.city = 'Bletchley'
+  u.tags.push('crypto')
+})
+
+const initials = computed(() => user.name.split(' ').map((s) => s[0]).join(''))
+// initials does NOT recompute when address.city changes.
+
+localStorage.setItem('user', JSON.stringify(unwrap(user)))
+```
+
+`reconcile(target, next, { key? })` merges a fresh payload (e.g. a hydration
+snapshot or a refetch) into `target` in place — unchanged nested values keep
+their proxy identity and notify nobody; only genuinely-changed paths flush.
+`key` controls array-item matching (default: index; pass a property name or a
+function for keyed reordering, e.g. `{ key: 'id' }`).
+
+`@aihu/reactive/helpers` bridges the tree ↔ tuple worlds: `toSignal`/
+`toSignals` lens reactive properties as `Signal` tuples, `toReactive` goes the
+other way (a `Signal<object>` viewed as a reactive-looking object),
+`reactivePick`/`reactiveOmit` are read-through views (no copies), and
+`reactiveComputed(fn)` keeps a reactive object in sync with `fn()` via an
+effect + `reconcile` — consumers reading one key only re-run when THAT key's
+value actually changes.
+
+**Non-wrappable values pass through unchanged**: `Date`, `Map`, `Set`,
+`RegExp`, class instances, DOM nodes, and frozen objects are stored raw and
+are replace-only — `reactive()` does not attempt to make them deeply
+reactive (see the design doc §8.8/§8.9 for the reasoning).
+
+Nothing shipped elsewhere changes: `signal`/`computed`/`effect`, and every
+composable in `@aihu/use`, keep their existing contracts verbatim. This is a
+purely additive new import, not new behavior on an old one.
+<!-- END_HANDWRITTEN: prose -->
+
+## Install
+
+<!-- BEGIN_AUTOGEN: install -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+```bash
+npm install @aihu/reactive
+# or
+bun add @aihu/reactive
+```
+
+<sub><i>Auto-generated against `@aihu/reactive@0.2.0`.</i></sub>
+
+<!-- END_AUTOGEN: install -->
+
+## Package facts
+
+<!-- BEGIN_AUTOGEN: stats -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+| | |
+|---|---|
+| **Version** | `0.2.0` |
+| **Tier** | G — State — fine-grained Proxy-backed deep reactive trees (lazy per-key nodes, plain-assignment writes) |
+| **Bundle size** | 1.28 kB (gz) — limit 1900 B |
+| **Published files** | 3 entries |
+| **License** | MIT |
+
+<sub><i>Auto-generated against `@aihu/reactive@0.2.0`.</i></sub>
+
+<!-- END_AUTOGEN: stats -->
+
+## Exports
+
+<!-- BEGIN_AUTOGEN: exports -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+| Subpath | ESM | CJS |
+|---|---|---|
+| `.` | `./dist/index.js` | `—` |
+| `./helpers` | `./dist/helpers.js` | `—` |
+
+<sub><i>Auto-generated against `@aihu/reactive@0.2.0`.</i></sub>
+
+<!-- END_AUTOGEN: exports -->
+
+## Dependencies
+
+<!-- BEGIN_AUTOGEN: deps -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+**Dependencies:**
+
+- `@aihu/signals` — `workspace:*`
+
+<sub><i>Auto-generated against `@aihu/reactive@0.2.0`.</i></sub>
+
+<!-- END_AUTOGEN: deps -->
+
+## See also
+
+<!-- BEGIN_AUTOGEN: see-also -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+- [@aihu/signals](../signals)
+- [@aihu/store](../store)
+- [Aihu framework root](../../README.md)
+
+<sub><i>Auto-generated against `@aihu/reactive@0.2.0`.</i></sub>
+
+<!-- END_AUTOGEN: see-also -->
+
+## License
+
+<!-- BEGIN_AUTOGEN: license -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+MIT — see [LICENSE](../../LICENSE).
+
+<sub><i>Auto-generated against `@aihu/reactive@0.2.0`.</i></sub>
+
+<!-- END_AUTOGEN: license -->

package/dist/helpers.d.ts

@@ -0,0 +1,29 @@
+import { Signal } from "@aihu/signals";
+
+//#region src/helpers/index.d.ts
+/** Lens a single property as a signal tuple — the tree → tuple bridge.
+ * Reads track the SAME per-key node the proxy's `get` trap would create
+ * (it IS that trap); writes go through the proxy's `set` trap. */
+declare function toSignal<T extends object, K extends keyof T>(t: T, k: K): Signal<T[K]>;
+/** Every own key as a signal tuple. Destructure-safe (each tuple is a live
+ * lens). */
+declare function toSignals<T extends object>(t: T): { [K in keyof T]: Signal<T[K]> };
+/** Signal-of-object → reactive-looking view. Whole-value read granularity;
+ * writes go through the tuple's setter with a shallow copy. The tuple →
+ * tree bridge. */
+declare function toReactive<T extends object>(source: Signal<T>): T;
+/** Read-through view over a subset of keys — no copies, tracking is
+ * preserved (each read forwards to the source proxy's own trap). */
+declare function reactivePick<T extends object, K extends keyof T>(s: T, ...keys: K[]): Pick<T, K>;
+/** Read-through view omitting a subset of keys — no copies, tracking is
+ * preserved. */
+declare function reactiveOmit<T extends object, K extends keyof T>(s: T, ...keys: K[]): Omit<T, K>;
+/** A reactive object kept in sync with `fn()` by an effect + `reconcile`.
+ * Scope-owned: `effect()` registers with the current scope like any other
+ * effect, so the enclosing `effectScope` disposes it. Per-key granularity
+ * — consumers that read one key only re-run when THAT key changes,
+ * because `reconcile` notifies only the keys that actually changed. */
+declare function reactiveComputed<T extends object>(fn: () => T): T;
+//#endregion
+export { reactiveComputed, reactiveOmit, reactivePick, toReactive, toSignal, toSignals };
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","names":[],"sources":["../src/helpers/index.ts"],"mappings":";;;;;AAgBA;iBAAgB,QAAA,mCAA2C,CAAA,CAAA,CAAG,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAA,GAAI,MAAA,CAAO,CAAA,CAAE,CAAA;;;iBAUpE,SAAA,kBAAA,CAA4B,CAAA,EAAG,CAAA,iBAAkB,CAAA,GAAI,MAAA,CAAO,CAAA,CAAE,CAAA;;;;iBAW9D,UAAA,kBAAA,CAA6B,MAAA,EAAQ,MAAA,CAAO,CAAA,IAAK,CAAA;;;iBAkCjD,YAAA,mCAA+C,CAAA,CAAA,CAAG,CAAA,EAAG,CAAA,KAAM,IAAA,EAAM,CAAA,KAAM,IAAA,CAAK,CAAA,EAAG,CAAA;;;iBAyB/E,YAAA,mCAA+C,CAAA,CAAA,CAAG,CAAA,EAAG,CAAA,KAAM,IAAA,EAAM,CAAA,KAAM,IAAA,CAAK,CAAA,EAAG,CAAA;;;;;;iBA4B/E,gBAAA,kBAAA,CAAmC,EAAA,QAAU,CAAA,GAAI,CAAA"}

package/dist/helpers.js

@@ -0,0 +1,135 @@
+import { effect } from "@aihu/signals";
+import { reactive, reconcile } from "@aihu/reactive";
+//#region src/helpers/index.ts
+/**
+* `@aihu/reactive/helpers` — the tree ↔ tuple bridge (design
+* docs/plans/2026-07-24-deep-reactivity.md §4.2).
+*
+* Imports the core (`@aihu/reactive`) by package NAME rather than a
+* relative path, and that self-import is marked `external` in
+* rolldown.config.ts (mirroring `@aihu/signals` being external to the
+* core row) — so this entry measures only the helper-specific code, never
+* a duplicate copy of the trap machinery.
+*/
+/** Lens a single property as a signal tuple — the tree → tuple bridge.
+* Reads track the SAME per-key node the proxy's `get` trap would create
+* (it IS that trap); writes go through the proxy's `set` trap. */
+function toSignal(t, k) {
+	const read = () => t[k];
+	const write = (next) => {
+		t[k] = typeof next === "function" ? next(t[k]) : next;
+	};
+	return [read, write];
+}
+/** Every own key as a signal tuple. Destructure-safe (each tuple is a live
+* lens). */
+function toSignals(t) {
+	const out = {};
+	for (const k of Object.keys(t)) out[k] = toSignal(t, k);
+	return out;
+}
+/** Signal-of-object → reactive-looking view. Whole-value read granularity;
+* writes go through the tuple's setter with a shallow copy. The tuple →
+* tree bridge. */
+function toReactive(source) {
+	const [read, write] = source;
+	return new Proxy({}, {
+		get(_t, key) {
+			return read()[key];
+		},
+		set(_t, key, value) {
+			write((prev) => ({
+				...prev,
+				[key]: value
+			}));
+			return true;
+		},
+		has(_t, key) {
+			return key in read();
+		},
+		deleteProperty(_t, key) {
+			write((prev) => {
+				const next = { ...prev };
+				delete next[key];
+				return next;
+			});
+			return true;
+		},
+		ownKeys() {
+			return Reflect.ownKeys(read());
+		},
+		getOwnPropertyDescriptor(_t, key) {
+			const obj = read();
+			if (!(key in obj)) return void 0;
+			return {
+				enumerable: true,
+				configurable: true,
+				value: obj[key]
+			};
+		}
+	});
+}
+/** Read-through view over a subset of keys — no copies, tracking is
+* preserved (each read forwards to the source proxy's own trap). */
+function reactivePick(s, ...keys) {
+	const keySet = new Set(keys);
+	return new Proxy({}, {
+		get(_t, key) {
+			return keySet.has(key) ? s[key] : void 0;
+		},
+		has(_t, key) {
+			return keySet.has(key) && key in s;
+		},
+		ownKeys() {
+			return [...keySet];
+		},
+		getOwnPropertyDescriptor(_t, key) {
+			if (!keySet.has(key)) return void 0;
+			return {
+				enumerable: true,
+				configurable: true,
+				value: s[key]
+			};
+		}
+	});
+}
+/** Read-through view omitting a subset of keys — no copies, tracking is
+* preserved. */
+function reactiveOmit(s, ...keys) {
+	const omitSet = new Set(keys);
+	return new Proxy({}, {
+		get(_t, key) {
+			return omitSet.has(key) ? void 0 : s[key];
+		},
+		has(_t, key) {
+			return !omitSet.has(key) && key in s;
+		},
+		ownKeys() {
+			return Reflect.ownKeys(s).filter((k) => !omitSet.has(k));
+		},
+		getOwnPropertyDescriptor(_t, key) {
+			if (omitSet.has(key)) return void 0;
+			return {
+				enumerable: true,
+				configurable: true,
+				value: s[key]
+			};
+		}
+	});
+}
+/** A reactive object kept in sync with `fn()` by an effect + `reconcile`.
+* Scope-owned: `effect()` registers with the current scope like any other
+* effect, so the enclosing `effectScope` disposes it. Per-key granularity
+* — consumers that read one key only re-run when THAT key changes,
+* because `reconcile` notifies only the keys that actually changed. */
+function reactiveComputed(fn) {
+	const target = reactive({});
+	effect(() => {
+		reconcile(target, fn());
+	});
+	return target;
+}
+//#endregion
+export { reactiveComputed, reactiveOmit, reactivePick, toReactive, toSignal, toSignals };
+
+//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","names":[],"sources":["../src/helpers/index.ts"],"sourcesContent":["/**\n * `@aihu/reactive/helpers` — the tree ↔ tuple bridge (design\n * docs/plans/2026-07-24-deep-reactivity.md §4.2).\n *\n * Imports the core (`@aihu/reactive`) by package NAME rather than a\n * relative path, and that self-import is marked `external` in\n * rolldown.config.ts (mirroring `@aihu/signals` being external to the\n * core row) — so this entry measures only the helper-specific code, never\n * a duplicate copy of the trap machinery.\n */\nimport { reactive, reconcile } from '@aihu/reactive'\nimport { effect, type Signal } from '@aihu/signals'\n\n/** Lens a single property as a signal tuple — the tree → tuple bridge.\n * Reads track the SAME per-key node the proxy's `get` trap would create\n * (it IS that trap); writes go through the proxy's `set` trap. */\nexport function toSignal<T extends object, K extends keyof T>(t: T, k: K): Signal<T[K]> {\n  const read = () => t[k]\n  const write = (next: unknown) => {\n    t[k] = typeof next === 'function' ? (next as (prev: T[K]) => T[K])(t[k]) : (next as T[K])\n  }\n  return [read, write] as unknown as Signal<T[K]>\n}\n\n/** Every own key as a signal tuple. Destructure-safe (each tuple is a live\n * lens). */\nexport function toSignals<T extends object>(t: T): { [K in keyof T]: Signal<T[K]> } {\n  const out = {} as { [K in keyof T]: Signal<T[K]> }\n  for (const k of Object.keys(t) as Array<keyof T>) {\n    out[k] = toSignal(t, k)\n  }\n  return out\n}\n\n/** Signal-of-object → reactive-looking view. Whole-value read granularity;\n * writes go through the tuple's setter with a shallow copy. The tuple →\n * tree bridge. */\nexport function toReactive<T extends object>(source: Signal<T>): T {\n  const [read, write] = source\n  return new Proxy({} as T, {\n    get(_t, key) {\n      return (read() as Record<PropertyKey, unknown>)[key]\n    },\n    set(_t, key, value) {\n      write((prev) => ({ ...(prev as object), [key]: value }) as T)\n      return true\n    },\n    has(_t, key) {\n      return key in (read() as object)\n    },\n    deleteProperty(_t, key) {\n      write((prev) => {\n        const next = { ...(prev as object) } as Record<PropertyKey, unknown>\n        delete next[key]\n        return next as T\n      })\n      return true\n    },\n    ownKeys() {\n      return Reflect.ownKeys(read() as object)\n    },\n    getOwnPropertyDescriptor(_t, key) {\n      const obj = read() as Record<PropertyKey, unknown>\n      if (!(key in obj)) return undefined\n      return { enumerable: true, configurable: true, value: obj[key] }\n    },\n  }) as T\n}\n\n/** Read-through view over a subset of keys — no copies, tracking is\n * preserved (each read forwards to the source proxy's own trap). */\nexport function reactivePick<T extends object, K extends keyof T>(s: T, ...keys: K[]): Pick<T, K> {\n  const keySet = new Set<PropertyKey>(keys)\n  return new Proxy({} as Pick<T, K>, {\n    get(_t, key) {\n      return keySet.has(key) ? (s as Record<PropertyKey, unknown>)[key] : undefined\n    },\n    has(_t, key) {\n      return keySet.has(key) && key in (s as object)\n    },\n    ownKeys() {\n      return [...keySet] as (string | symbol)[]\n    },\n    getOwnPropertyDescriptor(_t, key) {\n      if (!keySet.has(key)) return undefined\n      return {\n        enumerable: true,\n        configurable: true,\n        value: (s as Record<PropertyKey, unknown>)[key],\n      }\n    },\n  }) as Pick<T, K>\n}\n\n/** Read-through view omitting a subset of keys — no copies, tracking is\n * preserved. */\nexport function reactiveOmit<T extends object, K extends keyof T>(s: T, ...keys: K[]): Omit<T, K> {\n  const omitSet = new Set<PropertyKey>(keys)\n  return new Proxy({} as Omit<T, K>, {\n    get(_t, key) {\n      return omitSet.has(key) ? undefined : (s as Record<PropertyKey, unknown>)[key]\n    },\n    has(_t, key) {\n      return !omitSet.has(key) && key in (s as object)\n    },\n    ownKeys() {\n      return Reflect.ownKeys(s as object).filter((k) => !omitSet.has(k))\n    },\n    getOwnPropertyDescriptor(_t, key) {\n      if (omitSet.has(key)) return undefined\n      return {\n        enumerable: true,\n        configurable: true,\n        value: (s as Record<PropertyKey, unknown>)[key],\n      }\n    },\n  }) as Omit<T, K>\n}\n\n/** A reactive object kept in sync with `fn()` by an effect + `reconcile`.\n * Scope-owned: `effect()` registers with the current scope like any other\n * effect, so the enclosing `effectScope` disposes it. Per-key granularity\n * — consumers that read one key only re-run when THAT key changes,\n * because `reconcile` notifies only the keys that actually changed. */\nexport function reactiveComputed<T extends object>(fn: () => T): T {\n  const target = reactive({} as T)\n  effect(() => {\n    const next = fn()\n    reconcile(target, next)\n  })\n  return target\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,SAAgB,SAA8C,GAAM,GAAoB;CACtF,MAAM,aAAa,EAAE;CACrB,MAAM,SAAS,SAAkB;EAC/B,EAAE,KAAK,OAAO,SAAS,aAAc,KAA8B,EAAE,GAAG,GAAI;;CAE9E,OAAO,CAAC,MAAM,MAAM;;;;AAKtB,SAAgB,UAA4B,GAAwC;CAClF,MAAM,MAAM,EAAE;CACd,KAAK,MAAM,KAAK,OAAO,KAAK,EAAE,EAC5B,IAAI,KAAK,SAAS,GAAG,EAAE;CAEzB,OAAO;;;;;AAMT,SAAgB,WAA6B,QAAsB;CACjE,MAAM,CAAC,MAAM,SAAS;CACtB,OAAO,IAAI,MAAM,EAAE,EAAO;EACxB,IAAI,IAAI,KAAK;GACX,OAAQ,MAAM,CAAkC;;EAElD,IAAI,IAAI,KAAK,OAAO;GAClB,OAAO,UAAU;IAAE,GAAI;KAAkB,MAAM;IAAO,EAAO;GAC7D,OAAO;;EAET,IAAI,IAAI,KAAK;GACX,OAAO,OAAQ,MAAM;;EAEvB,eAAe,IAAI,KAAK;GACtB,OAAO,SAAS;IACd,MAAM,OAAO,EAAE,GAAI,MAAiB;IACpC,OAAO,KAAK;IACZ,OAAO;KACP;GACF,OAAO;;EAET,UAAU;GACR,OAAO,QAAQ,QAAQ,MAAM,CAAW;;EAE1C,yBAAyB,IAAI,KAAK;GAChC,MAAM,MAAM,MAAM;GAClB,IAAI,EAAE,OAAO,MAAM,OAAO,KAAA;GAC1B,OAAO;IAAE,YAAY;IAAM,cAAc;IAAM,OAAO,IAAI;IAAM;;EAEnE,CAAC;;;;AAKJ,SAAgB,aAAkD,GAAM,GAAG,MAAuB;CAChG,MAAM,SAAS,IAAI,IAAiB,KAAK;CACzC,OAAO,IAAI,MAAM,EAAE,EAAgB;EACjC,IAAI,IAAI,KAAK;GACX,OAAO,OAAO,IAAI,IAAI,GAAI,EAAmC,OAAO,KAAA;;EAEtE,IAAI,IAAI,KAAK;GACX,OAAO,OAAO,IAAI,IAAI,IAAI,OAAQ;;EAEpC,UAAU;GACR,OAAO,CAAC,GAAG,OAAO;;EAEpB,yBAAyB,IAAI,KAAK;GAChC,IAAI,CAAC,OAAO,IAAI,IAAI,EAAE,OAAO,KAAA;GAC7B,OAAO;IACL,YAAY;IACZ,cAAc;IACd,OAAQ,EAAmC;IAC5C;;EAEJ,CAAC;;;;AAKJ,SAAgB,aAAkD,GAAM,GAAG,MAAuB;CAChG,MAAM,UAAU,IAAI,IAAiB,KAAK;CAC1C,OAAO,IAAI,MAAM,EAAE,EAAgB;EACjC,IAAI,IAAI,KAAK;GACX,OAAO,QAAQ,IAAI,IAAI,GAAG,KAAA,IAAa,EAAmC;;EAE5E,IAAI,IAAI,KAAK;GACX,OAAO,CAAC,QAAQ,IAAI,IAAI,IAAI,OAAQ;;EAEtC,UAAU;GACR,OAAO,QAAQ,QAAQ,EAAY,CAAC,QAAQ,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;;EAEpE,yBAAyB,IAAI,KAAK;GAChC,IAAI,QAAQ,IAAI,IAAI,EAAE,OAAO,KAAA;GAC7B,OAAO;IACL,YAAY;IACZ,cAAc;IACd,OAAQ,EAAmC;IAC5C;;EAEJ,CAAC;;;;;;;AAQJ,SAAgB,iBAAmC,IAAgB;CACjE,MAAM,SAAS,SAAS,EAAE,CAAM;CAChC,aAAa;EAEX,UAAU,QADG,IACS,CAAC;GACvB;CACF,OAAO"}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+//#region src/internal.d.ts
+/**
+ * Wrap a plain object/array in a fine-grained reactive tree. Idempotent and
+ * identity-stable: `reactive(o) === reactive(o)`, `reactive(reactive(o)) ===
+ * reactive(o)`. Non-wrappable values (Date, Map, Set, class instances,
+ * frozen objects, primitives) are returned as-is.
+ */
+declare function reactive<T extends object>(source: T): T;
+/** True for a proxy produced by `reactive()`. */
+declare function isReactive(value: unknown): boolean;
+/** The raw object behind a reactive proxy (O(1), no traversal — writes
+ * unwrap, so the raw tree never contains proxies). Non-proxies pass
+ * through unchanged. */
+declare function unwrap<T>(value: T): T;
+/** Apply many writes as ONE flush. Equivalent to `batch(() => recipe(target))`
+ * — the "draft" IS the reactive proxy; writes apply immediately (design
+ * §8.6: NOT an Immer draft — a throwing recipe leaves partial writes, same
+ * non-atomic-on-error posture `batch()` already documents). */
+declare function mutate<T extends object>(target: T, recipe: (draft: T) => void): void;
+type ReconcileOptions = {
+  key?: PropertyKey | ((item: unknown) => unknown);
+};
+/**
+ * Merge `next` into `target` in place, preserving node identity for
+ * unchanged values and notifying ONLY changed paths. The hydration /
+ * refetch primitive. `key` controls array item matching (default: index),
+ * applied recursively to every array reconcile encounters, not only a
+ * top-level one.
+ */
+declare function reconcile<T extends object>(target: T, next: T, options?: ReconcileOptions): void;
+//#endregion
+export { isReactive, mutate, reactive, reconcile, unwrap };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/internal.ts"],"mappings":";;AA8PA;;;;;iBAAgB,QAAA,kBAAA,CAA2B,MAAA,EAAQ,CAAA,GAAI,CAAA;;iBAavC,UAAA,CAAW,KAAA;;;AAA3B;iBAOgB,MAAA,GAAA,CAAU,KAAA,EAAO,CAAA,GAAI,CAAA;;;;AAArC;iBAYgB,MAAA,kBAAA,CAAyB,MAAA,EAAQ,CAAA,EAAG,MAAA,GAAS,KAAA,EAAO,CAAA;AAAA,KAM/D,gBAAA;EAAqB,GAAA,GAAM,WAAA,KAAgB,IAAA;AAAA;;;;;;AANhD;;iBA2GgB,SAAA,kBAAA,CAA4B,MAAA,EAAQ,CAAA,EAAG,IAAA,EAAM,CAAA,EAAG,OAAA,GAAU,gBAAA"}

package/dist/index.js

@@ -0,0 +1,285 @@
+import { batch, signal } from "@aihu/signals";
+//#region src/internal.ts
+/**
+* `@aihu/reactive` — fine-grained Proxy-backed deep reactive trees on
+* `@aihu/signals` (docs/plans/2026-07-24-deep-reactivity.md).
+*
+* Mechanism (design §2.6/§2.7): a Solid-shaped node model — lazily allocated
+* per-(object, key) tracking nodes, one `signal(0, { equals: false })` per
+* touched key used as a pure version token (the VALUE lives on the raw
+* object; the node only carries subscription edges) — with Vue-shaped
+* write ergonomics: plain `obj.key = value` assignment through the `set`
+* trap, no `setStore(...)` path tuples.
+*
+* `@aihu/signals` is the sole dependency and is marked `external` in
+* rolldown.config.ts — this package adds zero bytes to the signals core row.
+*/
+/** raw → proxy. Stable so `reactive(o) === reactive(o)`. */
+const wrapMap = /* @__PURE__ */ new WeakMap();
+/** proxy → raw. `unwrap()` is a single lookup here — O(1), no traversal. */
+const rawMap = /* @__PURE__ */ new WeakMap();
+/** raw → per-key tracking node map. Lazily populated (design §2.7): a node
+* is allocated on the FIRST get-trap touch of a key, tracked or not. */
+const nodeMap = /* @__PURE__ */ new WeakMap();
+/** @internal — sentinel key for the per-object "shape" node: notified on
+* property add/delete, tracked by `ownKeys`/`has` (design §2.6). Never
+* collides with a real property key (own module-local symbol). */
+const KEYS = Symbol("aihu-reactive-keys");
+/** Array mutator methods that touch more than one index/length slot — run
+* inside `batch()` so e.g. `arr.push(a, b)` is one flush, not N (design
+* §2.6: "array mutating methods run inside batch()"). Intercepted directly
+* in the `get` trap rather than tracked as a plain property read: nobody
+* meaningfully subscribes to the identity of the `push` function itself. */
+const ARRAY_MUTATORS = new Set([
+	"push",
+	"pop",
+	"shift",
+	"unshift",
+	"splice",
+	"sort",
+	"reverse",
+	"fill",
+	"copyWithin"
+]);
+function getNodes(raw) {
+	let nodes = nodeMap.get(raw);
+	if (nodes === void 0) {
+		nodes = /* @__PURE__ */ new Map();
+		nodeMap.set(raw, nodes);
+	}
+	return nodes;
+}
+function getOrCreateNode(nodes, key) {
+	let node = nodes.get(key);
+	if (node === void 0) {
+		node = signal(0, { equals: false });
+		nodes.set(key, node);
+	}
+	return node;
+}
+function isArrayIndexKey(key) {
+	if (typeof key !== "string") return false;
+	if (key === "") return false;
+	const n = Number(key);
+	return Number.isInteger(n) && n >= 0 && String(n) === key;
+}
+/** Solid's `isWrappable`, minus the collection-type carve-outs this design
+* doesn't need (design §2.2, §2.6): plain objects and arrays, not frozen. */
+function isWrappable(v) {
+	if (Object.isFrozen(v)) return false;
+	if (Array.isArray(v)) return true;
+	const proto = Object.getPrototypeOf(v);
+	return proto === Object.prototype || proto === null;
+}
+function isPlainObjectLike(v) {
+	if (v === null || typeof v !== "object" || Array.isArray(v)) return false;
+	const proto = Object.getPrototypeOf(v);
+	return proto === Object.prototype || proto === null;
+}
+function sameContainerShape(a, b) {
+	if (Array.isArray(a) && Array.isArray(b)) return true;
+	return isPlainObjectLike(a) && isPlainObjectLike(b);
+}
+/** Recursively replace nested reactive proxies found inside a freshly
+* assigned plain container with their raw counterparts, IN PLACE, before
+* that container is stored on the raw tree (design §2.6/§8.4: "the raw
+* tree never contains proxies"). Plain `unwrap()` is a single WeakMap
+* lookup and only strips a DIRECTLY-assigned proxy — `outer.box = { inner:
+* someProxy }` would otherwise smuggle `someProxy` in under `box.inner`
+* since `box` itself was never a proxy. Walks only wrappable containers
+* (same class `isWrappable` recognizes); a `seen` WeakSet guards against
+* cyclic user data. */
+function unwrapDeep(value, seen) {
+	if (value === null || typeof value !== "object") return value;
+	const raw = rawMap.get(value);
+	const container = raw !== void 0 ? raw : value;
+	if (!isWrappable(container)) return container;
+	const visited = seen ?? /* @__PURE__ */ new WeakSet();
+	if (visited.has(container)) return container;
+	visited.add(container);
+	const rec = container;
+	for (const k of Reflect.ownKeys(rec)) {
+		const v = rec[k];
+		if (v !== null && typeof v === "object") rec[k] = unwrapDeep(v, visited);
+	}
+	return container;
+}
+const handlers = {
+	get(target, key, receiver) {
+		if (Array.isArray(target) && ARRAY_MUTATORS.has(key)) {
+			const fn = target[key];
+			return (...args) => batch(() => fn.apply(receiver, args));
+		}
+		getOrCreateNode(getNodes(target), key)[0]();
+		const res = target[key];
+		return res !== null && typeof res === "object" ? reactive(res) : res;
+	},
+	set(target, key, value) {
+		const isArray = Array.isArray(target);
+		const rawValue = unwrapDeep(value);
+		const record = target;
+		const hadKey = key in target;
+		const oldValue = record[key];
+		if (hadKey && Object.is(rawValue, oldValue)) return true;
+		const nodes = getNodes(target);
+		if (isArray && key === "length") {
+			const oldLen = oldValue;
+			record.length = rawValue;
+			const newLen = record.length;
+			const lengthNode = getOrCreateNode(nodes, "length");
+			if (newLen < oldLen) batch(() => {
+				lengthNode[1]((v) => v + 1);
+				for (let i = newLen; i < oldLen; i++) {
+					const idxNode = nodes.get(String(i));
+					if (idxNode !== void 0) idxNode[1]((v) => v + 1);
+				}
+			});
+			else lengthNode[1]((v) => v + 1);
+			return true;
+		}
+		record[key] = rawValue;
+		const keyNode = getOrCreateNode(nodes, key);
+		if (hadKey) {
+			keyNode[1]((v) => v + 1);
+			return true;
+		}
+		const companion = getOrCreateNode(nodes, isArray && isArrayIndexKey(key) ? "length" : KEYS);
+		batch(() => {
+			keyNode[1]((v) => v + 1);
+			companion[1]((v) => v + 1);
+		});
+		return true;
+	},
+	has(target, key) {
+		const nodes = getNodes(target);
+		getOrCreateNode(nodes, KEYS)[0]();
+		if (Array.isArray(target)) getOrCreateNode(nodes, "length")[0]();
+		return key in target;
+	},
+	deleteProperty(target, key) {
+		const had = key in target;
+		const ok = delete target[key];
+		if (had && ok) {
+			const nodes = getNodes(target);
+			const keyNode = nodes.get(key);
+			const keysNode = getOrCreateNode(nodes, KEYS);
+			batch(() => {
+				if (keyNode !== void 0) keyNode[1]((v) => v + 1);
+				keysNode[1]((v) => v + 1);
+			});
+		}
+		return ok;
+	},
+	ownKeys(target) {
+		const nodes = getNodes(target);
+		getOrCreateNode(nodes, KEYS)[0]();
+		if (Array.isArray(target)) getOrCreateNode(nodes, "length")[0]();
+		return Reflect.ownKeys(target);
+	}
+};
+/**
+* Wrap a plain object/array in a fine-grained reactive tree. Idempotent and
+* identity-stable: `reactive(o) === reactive(o)`, `reactive(reactive(o)) ===
+* reactive(o)`. Non-wrappable values (Date, Map, Set, class instances,
+* frozen objects, primitives) are returned as-is.
+*/
+function reactive(source) {
+	if (source === null || typeof source !== "object") return source;
+	if (rawMap.has(source)) return source;
+	const cached = wrapMap.get(source);
+	if (cached !== void 0) return cached;
+	if (!isWrappable(source)) return source;
+	const proxy = new Proxy(source, handlers);
+	wrapMap.set(source, proxy);
+	rawMap.set(proxy, source);
+	return proxy;
+}
+/** True for a proxy produced by `reactive()`. */
+function isReactive(value) {
+	return value !== null && typeof value === "object" && rawMap.has(value);
+}
+/** The raw object behind a reactive proxy (O(1), no traversal — writes
+* unwrap, so the raw tree never contains proxies). Non-proxies pass
+* through unchanged. */
+function unwrap(value) {
+	if (value !== null && typeof value === "object") {
+		const raw = rawMap.get(value);
+		if (raw !== void 0) return raw;
+	}
+	return value;
+}
+/** Apply many writes as ONE flush. Equivalent to `batch(() => recipe(target))`
+* — the "draft" IS the reactive proxy; writes apply immediately (design
+* §8.6: NOT an Immer draft — a throwing recipe leaves partial writes, same
+* non-atomic-on-error posture `batch()` already documents). */
+function mutate(target, recipe) {
+	batch(() => recipe(target));
+}
+function reconcileInto(proxy, next, options) {
+	const raw = unwrap(proxy);
+	if (Array.isArray(raw) && Array.isArray(next)) {
+		if (options?.key !== void 0) {
+			reconcileArrayKeyed(proxy, raw, next, options);
+			return;
+		}
+		for (let i = 0; i < next.length; i++) reconcileField(proxy, i, raw[i], next[i], i < raw.length, options);
+		if (next.length < raw.length) proxy.length = next.length;
+		return;
+	}
+	if (isPlainObjectLike(raw) && isPlainObjectLike(next)) {
+		for (const k of Reflect.ownKeys(next)) reconcileField(proxy, k, raw[k], next[k], Object.hasOwn(raw, k), options);
+		for (const k of Reflect.ownKeys(raw)) if (!Object.hasOwn(next, k)) delete proxy[k];
+	}
+}
+/** Reconcile one field. Reads for comparison come from the RAW values
+* (never through the proxy) so this can run safely inside the tracking
+* effect that drives `reactiveComputed` without the write-side of this
+* same reconcile becoming a read-side dependency of itself. Only the
+* write path (`proxy[key] = …`) touches the proxy.
+*
+* `hadKey` mirrors the `set` trap's own add-detection fix: `curVal` for a
+* key genuinely absent from `raw` reads as `undefined`, same as an
+* explicit `undefined` value would — `Object.is` alone can't tell "already
+* undefined" from "never existed" apart, so a payload adding an
+* explicitly-`undefined`-valued key would otherwise be silently dropped as
+* a no-op. */
+function reconcileField(proxy, key, curVal, nextVal, hadKey, options) {
+	if (sameContainerShape(curVal, nextVal)) reconcileInto(reactive(curVal), nextVal, options);
+	else if (!hadKey || !Object.is(curVal, nextVal)) proxy[key] = nextVal;
+}
+function reconcileArrayKeyed(proxy, raw, next, options) {
+	const keyOpt = options.key;
+	const idOf = typeof keyOpt === "function" ? keyOpt : (item) => item?.[keyOpt];
+	const byKey = /* @__PURE__ */ new Map();
+	for (const item of raw) byKey.set(idOf(item), item);
+	const merged = new Array(next.length);
+	for (let i = 0; i < next.length; i++) {
+		const nextItem = next[i];
+		const id = idOf(nextItem);
+		const match = byKey.get(id);
+		if (match !== void 0 && sameContainerShape(match, nextItem)) {
+			reconcileInto(reactive(match), nextItem, options);
+			merged[i] = match;
+			byKey.delete(id);
+		} else merged[i] = nextItem;
+	}
+	for (let i = 0; i < merged.length; i++) if (!Object.is(raw[i], merged[i])) proxy[i] = merged[i];
+	if (merged.length < raw.length) proxy.length = merged.length;
+}
+/**
+* Merge `next` into `target` in place, preserving node identity for
+* unchanged values and notifying ONLY changed paths. The hydration /
+* refetch primitive. `key` controls array item matching (default: index),
+* applied recursively to every array reconcile encounters, not only a
+* top-level one.
+*/
+function reconcile(target, next, options) {
+	const proxy = reactive(target);
+	batch(() => {
+		reconcileInto(proxy, next, options);
+	});
+}
+//#endregion
+export { isReactive, mutate, reactive, reconcile, unwrap };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/internal.ts"],"sourcesContent":["/**\n * `@aihu/reactive` — fine-grained Proxy-backed deep reactive trees on\n * `@aihu/signals` (docs/plans/2026-07-24-deep-reactivity.md).\n *\n * Mechanism (design §2.6/§2.7): a Solid-shaped node model — lazily allocated\n * per-(object, key) tracking nodes, one `signal(0, { equals: false })` per\n * touched key used as a pure version token (the VALUE lives on the raw\n * object; the node only carries subscription edges) — with Vue-shaped\n * write ergonomics: plain `obj.key = value` assignment through the `set`\n * trap, no `setStore(...)` path tuples.\n *\n * `@aihu/signals` is the sole dependency and is marked `external` in\n * rolldown.config.ts — this package adds zero bytes to the signals core row.\n */\nimport { batch, type Signal, signal } from '@aihu/signals'\n\n// ───────── Identity maps (design §2.6) ─────────\n\n/** raw → proxy. Stable so `reactive(o) === reactive(o)`. */\nconst wrapMap = new WeakMap<object, object>()\n/** proxy → raw. `unwrap()` is a single lookup here — O(1), no traversal. */\nconst rawMap = new WeakMap<object, object>()\n/** raw → per-key tracking node map. Lazily populated (design §2.7): a node\n * is allocated on the FIRST get-trap touch of a key, tracked or not. */\nconst nodeMap = new WeakMap<object, Map<PropertyKey, Signal<number>>>()\n\n/** @internal — sentinel key for the per-object \"shape\" node: notified on\n * property add/delete, tracked by `ownKeys`/`has` (design §2.6). Never\n * collides with a real property key (own module-local symbol). */\nconst KEYS: unique symbol = Symbol('aihu-reactive-keys')\n\n/** Array mutator methods that touch more than one index/length slot — run\n * inside `batch()` so e.g. `arr.push(a, b)` is one flush, not N (design\n * §2.6: \"array mutating methods run inside batch()\"). Intercepted directly\n * in the `get` trap rather than tracked as a plain property read: nobody\n * meaningfully subscribes to the identity of the `push` function itself. */\nconst ARRAY_MUTATORS = new Set<PropertyKey>([\n  'push',\n  'pop',\n  'shift',\n  'unshift',\n  'splice',\n  'sort',\n  'reverse',\n  'fill',\n  'copyWithin',\n])\n\nfunction getNodes(raw: object): Map<PropertyKey, Signal<number>> {\n  let nodes = nodeMap.get(raw)\n  if (nodes === undefined) {\n    nodes = new Map()\n    nodeMap.set(raw, nodes)\n  }\n  return nodes\n}\n\nfunction getOrCreateNode(\n  nodes: Map<PropertyKey, Signal<number>>,\n  key: PropertyKey,\n): Signal<number> {\n  let node = nodes.get(key)\n  if (node === undefined) {\n    node = signal(0, { equals: false })\n    nodes.set(key, node)\n  }\n  return node\n}\n\nfunction isArrayIndexKey(key: PropertyKey): boolean {\n  if (typeof key !== 'string') return false\n  if (key === '') return false\n  const n = Number(key)\n  return Number.isInteger(n) && n >= 0 && String(n) === key\n}\n\n/** Solid's `isWrappable`, minus the collection-type carve-outs this design\n * doesn't need (design §2.2, §2.6): plain objects and arrays, not frozen. */\nfunction isWrappable(v: object): boolean {\n  if (Object.isFrozen(v)) return false\n  if (Array.isArray(v)) return true\n  const proto = Object.getPrototypeOf(v)\n  return proto === Object.prototype || proto === null\n}\n\nfunction isPlainObjectLike(v: unknown): v is Record<PropertyKey, unknown> {\n  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false\n  const proto = Object.getPrototypeOf(v)\n  return proto === Object.prototype || proto === null\n}\n\nfunction sameContainerShape(a: unknown, b: unknown): boolean {\n  if (Array.isArray(a) && Array.isArray(b)) return true\n  return isPlainObjectLike(a) && isPlainObjectLike(b)\n}\n\n/** Recursively replace nested reactive proxies found inside a freshly\n * assigned plain container with their raw counterparts, IN PLACE, before\n * that container is stored on the raw tree (design §2.6/§8.4: \"the raw\n * tree never contains proxies\"). Plain `unwrap()` is a single WeakMap\n * lookup and only strips a DIRECTLY-assigned proxy — `outer.box = { inner:\n * someProxy }` would otherwise smuggle `someProxy` in under `box.inner`\n * since `box` itself was never a proxy. Walks only wrappable containers\n * (same class `isWrappable` recognizes); a `seen` WeakSet guards against\n * cyclic user data. */\nfunction unwrapDeep(value: unknown, seen?: WeakSet<object>): unknown {\n  if (value === null || typeof value !== 'object') return value\n  const raw = rawMap.get(value as object)\n  const container = raw !== undefined ? raw : (value as object)\n  if (!isWrappable(container)) return container\n  const visited = seen ?? new WeakSet<object>()\n  if (visited.has(container)) return container\n  visited.add(container)\n  const rec = container as Record<PropertyKey, unknown>\n  for (const k of Reflect.ownKeys(rec)) {\n    const v = rec[k]\n    if (v !== null && typeof v === 'object') {\n      rec[k] = unwrapDeep(v, visited)\n    }\n  }\n  return container\n}\n\n// ───────── Proxy traps (design §2.6) ─────────\n\nconst handlers: ProxyHandler<object> = {\n  get(target, key, receiver) {\n    if (Array.isArray(target) && ARRAY_MUTATORS.has(key)) {\n      const fn = (target as unknown as Record<PropertyKey, (...a: unknown[]) => unknown>)[key] as (\n        ...a: unknown[]\n      ) => unknown\n      // Apply with `this = receiver` (the proxy, not the raw target) so the\n      // method's own internal index/length writes route through OUR `set`\n      // trap — that's what makes `batch()` here collapse them into one\n      // flush instead of bypassing tracking entirely.\n      return (...args: unknown[]) => batch(() => fn.apply(receiver, args))\n    }\n    // First-touch allocation, tracked or not (design §2.7): the read() call\n    // below is the ordinary signal reader — `if (currentObserver !== null)\n    // linkAdd(...)` — so an untracked read allocates the node but no edge.\n    getOrCreateNode(getNodes(target), key)[0]()\n    const res = (target as Record<PropertyKey, unknown>)[key]\n    return res !== null && typeof res === 'object' ? reactive(res as object) : res\n  },\n\n  set(target, key, value) {\n    const isArray = Array.isArray(target)\n    const rawValue = unwrapDeep(value)\n    const record = target as Record<PropertyKey, unknown>\n    // Add-detection MUST run before the equality short-circuit below:\n    // assigning `undefined` to a key that does not yet exist has to still\n    // create it (plain-JS parity, design §2.1/§2.6) — `oldValue` for a\n    // missing key also reads as `undefined`, so checking `hadKey` first is\n    // what tells the two cases apart.\n    const hadKey = key in target\n    const oldValue = record[key]\n    // Equality short-circuit (design §2.6) — same Object.is rule and the\n    // same \"no allocation, no notify\" shape signal.ts's write() already\n    // applies to every tuple write. `obj.x = obj.x` is a correct no-op.\n    if (hadKey && Object.is(rawValue, oldValue)) return true\n\n    const nodes = getNodes(target)\n\n    // Array length assignment is the one write that can silently drop (or\n    // reintroduce) index properties without ever routing through\n    // `deleteProperty` — handle it explicitly so effects subscribed to a\n    // dropped index are notified. This is the exact path `reconcile()`'s\n    // truncation uses (`proxy.length = next.length`), so fixing it here\n    // fixes reconcile too (design §8.10's index-tracking model).\n    if (isArray && key === 'length') {\n      const oldLen = oldValue as number\n      record.length = rawValue as number\n      const newLen = record.length as number\n      const lengthNode = getOrCreateNode(nodes, 'length')\n      if (newLen < oldLen) {\n        batch(() => {\n          lengthNode[1]((v) => v + 1)\n          for (let i = newLen; i < oldLen; i++) {\n            const idxNode = nodes.get(String(i))\n            if (idxNode !== undefined) idxNode[1]((v) => v + 1)\n          }\n        })\n      } else {\n        lengthNode[1]((v) => v + 1)\n      }\n      return true\n    }\n\n    record[key] = rawValue\n    const keyNode = getOrCreateNode(nodes, key)\n    if (hadKey) {\n      // Plain value write on an existing key touches exactly one node —\n      // no batch needed (matches tuple-write semantics: one write, one\n      // flush).\n      keyNode[1]((v) => v + 1)\n      return true\n    }\n    // Add path: property add, or an array index write past the current\n    // length. Both touch the key's own node AND a shape companion node\n    // (KEYS for objects / length for array-index adds) — batched together\n    // so the trap never produces two back-to-back synchronous drains for\n    // one authored assignment (design §2.6). `ownKeys`/`has` track BOTH\n    // nodes for arrays (below), so bumping `length` alone still wakes\n    // Object.keys/for-in/`in` watchers on an index add.\n    const companion = getOrCreateNode(nodes, isArray && isArrayIndexKey(key) ? 'length' : KEYS)\n    batch(() => {\n      keyNode[1]((v) => v + 1)\n      companion[1]((v) => v + 1)\n    })\n    return true\n  },\n\n  has(target, key) {\n    const nodes = getNodes(target)\n    getOrCreateNode(nodes, KEYS)[0]()\n    // Arrays notify index adds via the `length` node, not KEYS (see\n    // `set`) — track it too so `'k' in arr` reacts to shape changes made\n    // through an index write, not only through defineProperty-shaped adds.\n    if (Array.isArray(target)) getOrCreateNode(nodes, 'length')[0]()\n    return key in target\n  },\n\n  deleteProperty(target, key) {\n    const had = key in target\n    const ok = delete (target as Record<PropertyKey, unknown>)[key]\n    if (had && ok) {\n      const nodes = getNodes(target)\n      const keyNode = nodes.get(key)\n      const keysNode = getOrCreateNode(nodes, KEYS)\n      batch(() => {\n        if (keyNode !== undefined) keyNode[1]((v) => v + 1)\n        keysNode[1]((v) => v + 1)\n      })\n    }\n    return ok\n  },\n\n  ownKeys(target) {\n    const nodes = getNodes(target)\n    getOrCreateNode(nodes, KEYS)[0]()\n    // See `has` above: array index adds bump `length`, not KEYS.\n    if (Array.isArray(target)) getOrCreateNode(nodes, 'length')[0]()\n    return Reflect.ownKeys(target)\n  },\n}\n\n// ───────── Public core API (design §4.1) ─────────\n\n/**\n * Wrap a plain object/array in a fine-grained reactive tree. Idempotent and\n * identity-stable: `reactive(o) === reactive(o)`, `reactive(reactive(o)) ===\n * reactive(o)`. Non-wrappable values (Date, Map, Set, class instances,\n * frozen objects, primitives) are returned as-is.\n */\nexport function reactive<T extends object>(source: T): T {\n  if (source === null || typeof source !== 'object') return source\n  if (rawMap.has(source as object)) return source // already a proxy\n  const cached = wrapMap.get(source as object)\n  if (cached !== undefined) return cached as T\n  if (!isWrappable(source as object)) return source\n  const proxy = new Proxy(source as object, handlers) as T\n  wrapMap.set(source as object, proxy as object)\n  rawMap.set(proxy as object, source as object)\n  return proxy\n}\n\n/** True for a proxy produced by `reactive()`. */\nexport function isReactive(value: unknown): boolean {\n  return value !== null && typeof value === 'object' && rawMap.has(value as object)\n}\n\n/** The raw object behind a reactive proxy (O(1), no traversal — writes\n * unwrap, so the raw tree never contains proxies). Non-proxies pass\n * through unchanged. */\nexport function unwrap<T>(value: T): T {\n  if (value !== null && typeof value === 'object') {\n    const raw = rawMap.get(value as object)\n    if (raw !== undefined) return raw as T\n  }\n  return value\n}\n\n/** Apply many writes as ONE flush. Equivalent to `batch(() => recipe(target))`\n * — the \"draft\" IS the reactive proxy; writes apply immediately (design\n * §8.6: NOT an Immer draft — a throwing recipe leaves partial writes, same\n * non-atomic-on-error posture `batch()` already documents). */\nexport function mutate<T extends object>(target: T, recipe: (draft: T) => void): void {\n  batch(() => recipe(target))\n}\n\n// ───────── reconcile (design §4.1, §7.2, §9) ─────────\n\ntype ReconcileOptions = { key?: PropertyKey | ((item: unknown) => unknown) }\n\nfunction reconcileInto(proxy: object, next: unknown, options?: ReconcileOptions): void {\n  const raw = unwrap(proxy)\n  if (Array.isArray(raw) && Array.isArray(next)) {\n    // `key` must apply at every array encountered during the recursion,\n    // not only a top-level array (design intent: `reconcile(state, payload,\n    // { key: 'id' })` where `state.rows` is a nested array) — falling back\n    // to index matching here would silently re-identity rows on a reorder.\n    if (options?.key !== undefined) {\n      reconcileArrayKeyed(proxy as unknown[], raw, next, options)\n      return\n    }\n    for (let i = 0; i < next.length; i++) {\n      reconcileField(proxy, i, (raw as unknown[])[i], next[i], i < raw.length, options)\n    }\n    if (next.length < raw.length) (proxy as unknown[]).length = next.length\n    return\n  }\n  if (isPlainObjectLike(raw) && isPlainObjectLike(next)) {\n    for (const k of Reflect.ownKeys(next)) {\n      reconcileField(proxy, k, raw[k], next[k], Object.hasOwn(raw, k), options)\n    }\n    for (const k of Reflect.ownKeys(raw)) {\n      if (!Object.hasOwn(next, k)) {\n        delete (proxy as Record<PropertyKey, unknown>)[k]\n      }\n    }\n  }\n}\n\n/** Reconcile one field. Reads for comparison come from the RAW values\n * (never through the proxy) so this can run safely inside the tracking\n * effect that drives `reactiveComputed` without the write-side of this\n * same reconcile becoming a read-side dependency of itself. Only the\n * write path (`proxy[key] = …`) touches the proxy.\n *\n * `hadKey` mirrors the `set` trap's own add-detection fix: `curVal` for a\n * key genuinely absent from `raw` reads as `undefined`, same as an\n * explicit `undefined` value would — `Object.is` alone can't tell \"already\n * undefined\" from \"never existed\" apart, so a payload adding an\n * explicitly-`undefined`-valued key would otherwise be silently dropped as\n * a no-op. */\nfunction reconcileField(\n  proxy: object,\n  key: PropertyKey,\n  curVal: unknown,\n  nextVal: unknown,\n  hadKey: boolean,\n  options?: ReconcileOptions,\n): void {\n  if (sameContainerShape(curVal, nextVal)) {\n    reconcileInto(reactive(curVal as object), nextVal, options)\n  } else if (!hadKey || !Object.is(curVal, nextVal)) {\n    ;(proxy as Record<PropertyKey, unknown>)[key] = nextVal\n  }\n}\n\nfunction reconcileArrayKeyed(\n  proxy: unknown[],\n  raw: unknown[],\n  next: unknown[],\n  options: ReconcileOptions,\n): void {\n  const keyOpt = options.key as PropertyKey | ((item: unknown) => unknown)\n  const idOf =\n    typeof keyOpt === 'function'\n      ? keyOpt\n      : (item: unknown) => (item as Record<PropertyKey, unknown> | null)?.[keyOpt]\n  const byKey = new Map<unknown, unknown>()\n  for (const item of raw) byKey.set(idOf(item), item)\n  const merged: unknown[] = new Array(next.length)\n  for (let i = 0; i < next.length; i++) {\n    const nextItem = next[i]\n    const id = idOf(nextItem)\n    const match = byKey.get(id)\n    if (match !== undefined && sameContainerShape(match, nextItem)) {\n      reconcileInto(reactive(match as object), nextItem, options)\n      merged[i] = match\n      // Consume the match: a duplicate key in `next` must NOT alias a\n      // second array slot onto the same raw object (that would silently\n      // make `proxy[i] === proxy[j]`, so a later write to one row mutates\n      // the other). Unmatched duplicates fall through to a fresh value.\n      byKey.delete(id)\n    } else {\n      merged[i] = nextItem\n    }\n  }\n  for (let i = 0; i < merged.length; i++) {\n    if (!Object.is(raw[i], merged[i])) proxy[i] = merged[i]\n  }\n  if (merged.length < raw.length) proxy.length = merged.length\n}\n\n/**\n * Merge `next` into `target` in place, preserving node identity for\n * unchanged values and notifying ONLY changed paths. The hydration /\n * refetch primitive. `key` controls array item matching (default: index),\n * applied recursively to every array reconcile encounters, not only a\n * top-level one.\n */\nexport function reconcile<T extends object>(target: T, next: T, options?: ReconcileOptions): void {\n  const proxy = reactive(target)\n  batch(() => {\n    reconcileInto(proxy as object, next, options)\n  })\n}\n\n// ───────── Test-only introspection ─────────\n//\n// NOT re-exported from index.ts (the \".\" entry stays exactly the public\n// API above) — reached only via a direct relative import from tests, the\n// same pattern packages/signals/src/signal.ts uses for `__hostOf` /\n// `__inspectGraph`. Since index.ts never references this binding, it is\n// dead-code-eliminated out of the measured `dist/index.js` (design §5,\n// §12 acceptance #1/#2 — this must never move the size row).\n\n/** @internal — test-only: the read function of the per-key tracking node\n * for `(raw, key)`, or `undefined` if that key has never been touched\n * through the proxy's `get`/`set` trap. Compose with `@aihu/signals`'\n * `__hostOf`/`__inspectGraph` to assert §2.7's allocation contract. */\nexport function __nodeOf(raw: object, key: PropertyKey): (() => number) | undefined {\n  return nodeMap.get(raw)?.get(key)?.[0]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAmBA,MAAM,0BAAU,IAAI,SAAyB;;AAE7C,MAAM,yBAAS,IAAI,SAAyB;;;AAG5C,MAAM,0BAAU,IAAI,SAAmD;;;;AAKvE,MAAM,OAAsB,OAAO,qBAAqB;;;;;;AAOxD,MAAM,iBAAiB,IAAI,IAAiB;CAC1C;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;AAEF,SAAS,SAAS,KAA+C;CAC/D,IAAI,QAAQ,QAAQ,IAAI,IAAI;CAC5B,IAAI,UAAU,KAAA,GAAW;EACvB,wBAAQ,IAAI,KAAK;EACjB,QAAQ,IAAI,KAAK,MAAM;;CAEzB,OAAO;;AAGT,SAAS,gBACP,OACA,KACgB;CAChB,IAAI,OAAO,MAAM,IAAI,IAAI;CACzB,IAAI,SAAS,KAAA,GAAW;EACtB,OAAO,OAAO,GAAG,EAAE,QAAQ,OAAO,CAAC;EACnC,MAAM,IAAI,KAAK,KAAK;;CAEtB,OAAO;;AAGT,SAAS,gBAAgB,KAA2B;CAClD,IAAI,OAAO,QAAQ,UAAU,OAAO;CACpC,IAAI,QAAQ,IAAI,OAAO;CACvB,MAAM,IAAI,OAAO,IAAI;CACrB,OAAO,OAAO,UAAU,EAAE,IAAI,KAAK,KAAK,OAAO,EAAE,KAAK;;;;AAKxD,SAAS,YAAY,GAAoB;CACvC,IAAI,OAAO,SAAS,EAAE,EAAE,OAAO;CAC/B,IAAI,MAAM,QAAQ,EAAE,EAAE,OAAO;CAC7B,MAAM,QAAQ,OAAO,eAAe,EAAE;CACtC,OAAO,UAAU,OAAO,aAAa,UAAU;;AAGjD,SAAS,kBAAkB,GAA+C;CACxE,IAAI,MAAM,QAAQ,OAAO,MAAM,YAAY,MAAM,QAAQ,EAAE,EAAE,OAAO;CACpE,MAAM,QAAQ,OAAO,eAAe,EAAE;CACtC,OAAO,UAAU,OAAO,aAAa,UAAU;;AAGjD,SAAS,mBAAmB,GAAY,GAAqB;CAC3D,IAAI,MAAM,QAAQ,EAAE,IAAI,MAAM,QAAQ,EAAE,EAAE,OAAO;CACjD,OAAO,kBAAkB,EAAE,IAAI,kBAAkB,EAAE;;;;;;;;;;;AAYrD,SAAS,WAAW,OAAgB,MAAiC;CACnE,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU,OAAO;CACxD,MAAM,MAAM,OAAO,IAAI,MAAgB;CACvC,MAAM,YAAY,QAAQ,KAAA,IAAY,MAAO;CAC7C,IAAI,CAAC,YAAY,UAAU,EAAE,OAAO;CACpC,MAAM,UAAU,wBAAQ,IAAI,SAAiB;CAC7C,IAAI,QAAQ,IAAI,UAAU,EAAE,OAAO;CACnC,QAAQ,IAAI,UAAU;CACtB,MAAM,MAAM;CACZ,KAAK,MAAM,KAAK,QAAQ,QAAQ,IAAI,EAAE;EACpC,MAAM,IAAI,IAAI;EACd,IAAI,MAAM,QAAQ,OAAO,MAAM,UAC7B,IAAI,KAAK,WAAW,GAAG,QAAQ;;CAGnC,OAAO;;AAKT,MAAM,WAAiC;CACrC,IAAI,QAAQ,KAAK,UAAU;EACzB,IAAI,MAAM,QAAQ,OAAO,IAAI,eAAe,IAAI,IAAI,EAAE;GACpD,MAAM,KAAM,OAAwE;GAOpF,QAAQ,GAAG,SAAoB,YAAY,GAAG,MAAM,UAAU,KAAK,CAAC;;EAKtE,gBAAgB,SAAS,OAAO,EAAE,IAAI,CAAC,IAAI;EAC3C,MAAM,MAAO,OAAwC;EACrD,OAAO,QAAQ,QAAQ,OAAO,QAAQ,WAAW,SAAS,IAAc,GAAG;;CAG7E,IAAI,QAAQ,KAAK,OAAO;EACtB,MAAM,UAAU,MAAM,QAAQ,OAAO;EACrC,MAAM,WAAW,WAAW,MAAM;EAClC,MAAM,SAAS;EAMf,MAAM,SAAS,OAAO;EACtB,MAAM,WAAW,OAAO;EAIxB,IAAI,UAAU,OAAO,GAAG,UAAU,SAAS,EAAE,OAAO;EAEpD,MAAM,QAAQ,SAAS,OAAO;EAQ9B,IAAI,WAAW,QAAQ,UAAU;GAC/B,MAAM,SAAS;GACf,OAAO,SAAS;GAChB,MAAM,SAAS,OAAO;GACtB,MAAM,aAAa,gBAAgB,OAAO,SAAS;GACnD,IAAI,SAAS,QACX,YAAY;IACV,WAAW,IAAI,MAAM,IAAI,EAAE;IAC3B,KAAK,IAAI,IAAI,QAAQ,IAAI,QAAQ,KAAK;KACpC,MAAM,UAAU,MAAM,IAAI,OAAO,EAAE,CAAC;KACpC,IAAI,YAAY,KAAA,GAAW,QAAQ,IAAI,MAAM,IAAI,EAAE;;KAErD;QAEF,WAAW,IAAI,MAAM,IAAI,EAAE;GAE7B,OAAO;;EAGT,OAAO,OAAO;EACd,MAAM,UAAU,gBAAgB,OAAO,IAAI;EAC3C,IAAI,QAAQ;GAIV,QAAQ,IAAI,MAAM,IAAI,EAAE;GACxB,OAAO;;EAST,MAAM,YAAY,gBAAgB,OAAO,WAAW,gBAAgB,IAAI,GAAG,WAAW,KAAK;EAC3F,YAAY;GACV,QAAQ,IAAI,MAAM,IAAI,EAAE;GACxB,UAAU,IAAI,MAAM,IAAI,EAAE;IAC1B;EACF,OAAO;;CAGT,IAAI,QAAQ,KAAK;EACf,MAAM,QAAQ,SAAS,OAAO;EAC9B,gBAAgB,OAAO,KAAK,CAAC,IAAI;EAIjC,IAAI,MAAM,QAAQ,OAAO,EAAE,gBAAgB,OAAO,SAAS,CAAC,IAAI;EAChE,OAAO,OAAO;;CAGhB,eAAe,QAAQ,KAAK;EAC1B,MAAM,MAAM,OAAO;EACnB,MAAM,KAAK,OAAQ,OAAwC;EAC3D,IAAI,OAAO,IAAI;GACb,MAAM,QAAQ,SAAS,OAAO;GAC9B,MAAM,UAAU,MAAM,IAAI,IAAI;GAC9B,MAAM,WAAW,gBAAgB,OAAO,KAAK;GAC7C,YAAY;IACV,IAAI,YAAY,KAAA,GAAW,QAAQ,IAAI,MAAM,IAAI,EAAE;IACnD,SAAS,IAAI,MAAM,IAAI,EAAE;KACzB;;EAEJ,OAAO;;CAGT,QAAQ,QAAQ;EACd,MAAM,QAAQ,SAAS,OAAO;EAC9B,gBAAgB,OAAO,KAAK,CAAC,IAAI;EAEjC,IAAI,MAAM,QAAQ,OAAO,EAAE,gBAAgB,OAAO,SAAS,CAAC,IAAI;EAChE,OAAO,QAAQ,QAAQ,OAAO;;CAEjC;;;;;;;AAUD,SAAgB,SAA2B,QAAc;CACvD,IAAI,WAAW,QAAQ,OAAO,WAAW,UAAU,OAAO;CAC1D,IAAI,OAAO,IAAI,OAAiB,EAAE,OAAO;CACzC,MAAM,SAAS,QAAQ,IAAI,OAAiB;CAC5C,IAAI,WAAW,KAAA,GAAW,OAAO;CACjC,IAAI,CAAC,YAAY,OAAiB,EAAE,OAAO;CAC3C,MAAM,QAAQ,IAAI,MAAM,QAAkB,SAAS;CACnD,QAAQ,IAAI,QAAkB,MAAgB;CAC9C,OAAO,IAAI,OAAiB,OAAiB;CAC7C,OAAO;;;AAIT,SAAgB,WAAW,OAAyB;CAClD,OAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,OAAO,IAAI,MAAgB;;;;;AAMnF,SAAgB,OAAU,OAAa;CACrC,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU;EAC/C,MAAM,MAAM,OAAO,IAAI,MAAgB;EACvC,IAAI,QAAQ,KAAA,GAAW,OAAO;;CAEhC,OAAO;;;;;;AAOT,SAAgB,OAAyB,QAAW,QAAkC;CACpF,YAAY,OAAO,OAAO,CAAC;;AAO7B,SAAS,cAAc,OAAe,MAAe,SAAkC;CACrF,MAAM,MAAM,OAAO,MAAM;CACzB,IAAI,MAAM,QAAQ,IAAI,IAAI,MAAM,QAAQ,KAAK,EAAE;EAK7C,IAAI,SAAS,QAAQ,KAAA,GAAW;GAC9B,oBAAoB,OAAoB,KAAK,MAAM,QAAQ;GAC3D;;EAEF,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAC/B,eAAe,OAAO,GAAI,IAAkB,IAAI,KAAK,IAAI,IAAI,IAAI,QAAQ,QAAQ;EAEnF,IAAI,KAAK,SAAS,IAAI,QAAQ,MAAqB,SAAS,KAAK;EACjE;;CAEF,IAAI,kBAAkB,IAAI,IAAI,kBAAkB,KAAK,EAAE;EACrD,KAAK,MAAM,KAAK,QAAQ,QAAQ,KAAK,EACnC,eAAe,OAAO,GAAG,IAAI,IAAI,KAAK,IAAI,OAAO,OAAO,KAAK,EAAE,EAAE,QAAQ;EAE3E,KAAK,MAAM,KAAK,QAAQ,QAAQ,IAAI,EAClC,IAAI,CAAC,OAAO,OAAO,MAAM,EAAE,EACzB,OAAQ,MAAuC;;;;;;;;;;;;;;;AAkBvD,SAAS,eACP,OACA,KACA,QACA,SACA,QACA,SACM;CACN,IAAI,mBAAmB,QAAQ,QAAQ,EACrC,cAAc,SAAS,OAAiB,EAAE,SAAS,QAAQ;MACtD,IAAI,CAAC,UAAU,CAAC,OAAO,GAAG,QAAQ,QAAQ,EAC9C,MAAwC,OAAO;;AAIpD,SAAS,oBACP,OACA,KACA,MACA,SACM;CACN,MAAM,SAAS,QAAQ;CACvB,MAAM,OACJ,OAAO,WAAW,aACd,UACC,SAAmB,OAA+C;CACzE,MAAM,wBAAQ,IAAI,KAAuB;CACzC,KAAK,MAAM,QAAQ,KAAK,MAAM,IAAI,KAAK,KAAK,EAAE,KAAK;CACnD,MAAM,SAAoB,IAAI,MAAM,KAAK,OAAO;CAChD,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;EACpC,MAAM,WAAW,KAAK;EACtB,MAAM,KAAK,KAAK,SAAS;EACzB,MAAM,QAAQ,MAAM,IAAI,GAAG;EAC3B,IAAI,UAAU,KAAA,KAAa,mBAAmB,OAAO,SAAS,EAAE;GAC9D,cAAc,SAAS,MAAgB,EAAE,UAAU,QAAQ;GAC3D,OAAO,KAAK;GAKZ,MAAM,OAAO,GAAG;SAEhB,OAAO,KAAK;;CAGhB,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KACjC,IAAI,CAAC,OAAO,GAAG,IAAI,IAAI,OAAO,GAAG,EAAE,MAAM,KAAK,OAAO;CAEvD,IAAI,OAAO,SAAS,IAAI,QAAQ,MAAM,SAAS,OAAO;;;;;;;;;AAUxD,SAAgB,UAA4B,QAAW,MAAS,SAAkC;CAChG,MAAM,QAAQ,SAAS,OAAO;CAC9B,YAAY;EACV,cAAc,OAAiB,MAAM,QAAQ;GAC7C"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@aihu/reactive",
+  "version": "0.2.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./helpers": {
+      "types": "./dist/helpers.d.ts",
+      "import": "./dist/helpers.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@aihu/signals": "0.5.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && rolldown -c",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "description": "Fine-grained Proxy-backed deep reactive trees on aihu signals — lazy per-(object,key) tracking nodes, plain-assignment writes, mutate/reconcile.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fellwork/aihu.git",
+    "directory": "packages/reactive"
+  },
+  "homepage": "https://github.com/fellwork/aihu/tree/main/packages/reactive#readme",
+  "bugs": "https://github.com/fellwork/aihu/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}