ustor 0.0.9 → 0.2.0

package/README.md

@@ -1,244 +1,687 @@
 # UStor
 
-[![tests](https://github.com/kethan/ustor/actions/workflows/node.js.yml/badge.svg)](https://github.com/ustor/actions/workflows/node.js.yml) [![Version](https://img.shields.io/npm/v/ustor.svg?color=success&style=flat-square)](https://www.npmjs.com/package/ustor) [![Badge size](https://deno.bundlejs.com/badge?q=ustor&treeshake=[*]&config={"compression":"brotli"})](https://unpkg.com/ustor) [![Badge size](https://deno.bundlejs.com/badge?q=ustor&treeshake=[*]&config={"compression":"gzip"})](https://unpkg.com/ustor)
+[![tests](https://github.com/kethan/ustor/actions/workflows/node.js.yml/badge.svg)](https://github.com/kethan/ustor/actions/workflows/node.js.yml)
+[![Version](https://img.shields.io/npm/v/ustor.svg?color=success&style=flat-square)](https://www.npmjs.com/package/ustor)
+[![Bundle size](https://deno.bundlejs.com/badge?q=ustor&treeshake=[*]&config={%22compression%22:%22brotli%22})](https://bundlejs.com/?q=ustor)
 
-# Reactive Store Library
+A tiny, dependency-free reactive store for JavaScript objects and arrays. UStor uses your signal implementation instead of bundling a reactivity engine.
 
-This library provides a powerful reactivity system for creating stateful objects using signals, integrated seamlessly into JavaScript objects and arrays. This library does not depend on any specific reactive library and can be used by any UI framework to manage and react to changes in state effectively.
+- **Small:** about 1.8 KiB minified and less than 1 KiB gzipped.
+- **Deeply reactive:** nested objects, arrays, getters, and existing signals.
+- **Framework-friendly:** 16 tested signal/store adapters plus optional React hooks.
+- **SSR-ready:** server rendering and hydration are tested.
+- **Typed:** TypeScript declarations for the core and React entry points.
+- **Interoperable:** ESM, CommonJS, IIFE, and UMD builds.
 
-## Table of Contents
+## Contents
 
 - [Installation](#installation)
-- [Setup](#setup)
-- [API](#api)
-  - [store(values, proto)](#storevalues-proto)
-  - [is(value)](#isvalue)
-  - [api.is](#apiis)
-  - [api.signal](#apisignal)
-  - [api.get](#apiget)
-  - [api.set](#apiset)
-- [Usage](#usage)
-  - [Basic Usage](#basic-usage)
-  - [Advanced Usage](#advanced-usage)
-  - [Deeply Nested Structures](#deeply-nested-structures)
-  - [Arrays and Objects](#arrays-and-objects)
-  - [Reactivity and Effects](#reactivity-and-effects)
-- [Integration with Solid.js, Preact Signals or any](#integration-with-solidjs-preact-signals-or-any)
+- [Quickstart](#quickstart)
+- [Common use cases](#common-use-cases)
+- [API reference](#api-reference)
+- [Arrays](#arrays)
+- [Supported adapters](#supported-adapters)
+- [Porting any signal library](#porting-any-signal-library)
+- [React](#react)
+- [SSR and Next.js](#ssr-and-nextjs)
+- [TypeScript](#typescript)
+- [Profiling and memory analysis](#profiling-and-memory-analysis)
+- [Production notes](#production-notes)
+- [Development](#development)
 
 ## Installation
 
-To use this library, you can install it using npm or yarn:
-
 ```bash
 npm install ustor
-yarn add ustor
 ```
 
-This library can be integrated with `solid-js`, `@preact/signals-core`, `ulive`, `usignal`, `oby`, `sinuous` any other libarary you can think of for managing reactive signals.
+Install the signal library you want to use. The examples below use `@preact/signals-core`:
+
+```bash
+npm install @preact/signals-core
+```
+
+UStor targets modern JavaScript environments with `Proxy`, `Reflect`, `WeakMap`, and `Object.hasOwn`. The runtime is not transpiled or polyfilled for legacy browsers.
 
-## Setup
+## Quickstart
 
-First, import the `store` function and the `api` object. You need to initialize `api` with your preferred signal implementation.
+Configure the adapter once, before creating stores:
 
 ```javascript
-import { store, api } from "./src";
-import { createSignal } from "solid-js";
-// import { signal } from '@preact/signals-core'; // 'usignal' 'ulive'
+import { store, api } from "ustor";
+import { signal, computed, effect } from "@preact/signals-core";
+
+Object.assign(api, {
+	signal,
+	memo: computed,
+	effect,
+	get: (value) => value.value,
+	getMemo: (value) => value.value,
+	set: (target, value) => { target.value = value; },
+	is: (value) => typeof value?.peek === "function",
+});
+```
 
-// Solid.js setup
-api.signal = createSignal;
-api.get = (v) => v[0]();
-api.set = (signal, v) => signal[1](v);
-api.is = (v) =>
-	(Array.isArray(v) &&
-		typeof v[0] === "function" &&
-		typeof v[1] === "function") ||
-	v[0]?.name?.includes("readSignal");
+Create a store and use ordinary property reads and writes:
 
-// @preact/signals-core, usignal or ulive setup
-api.signal = signal;
-api.get = (v) => v.value;
-api.set = (signal, v) => (signal.value = v);
-api.is = (v) => v?.peek;
+```javascript
+const state = store({
+	count: 1,
+	items: [1, 2],
+	get double() {
+		return this.count * 2;
+	},
+});
+
+const dispose = effect(() => {
+	console.log(state.double, state.items.length);
+});
+
+state.count = 3;       // effects using count or double update
+state.items.push(3);   // array mutations are reactive too
+
+console.log(state.count);        // 3
+console.log(state.double);       // 6
+console.log(state.$count.value); // 3: the underlying Preact signal
+
+dispose();
 ```
 
-## API
+**Important:** `api` is shared by stores from the same UStor module instance. Configure one adapter and do not switch implementations while existing stores are still in use.
 
-### `store(values, proto)`
+## Common use cases
 
-The `store` function creates a stateful object that automatically converts properties into reactive signals.
+### Shopping cart with reactive items and totals
 
-- **values**: The initial values for the store, which can be objects, arrays, or primitives.
-- **proto**: Optional prototype to set for the new store object.
+```javascript
+const cart = store({
+	items: [],
+	get total() {
+		return this.items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+	},
+});
 
-The function returns a reactive store object that maintains the structure of the original `values` while adding reactivity.
+cart.items.push({ id: "book", price: 12, quantity: 1 });
+console.log(cart.total); // 12
 
-### `is(value)`
+cart.items[0].quantity = 2;
+console.log(cart.total); // 24
 
-The `is` function checks if a given value is a reactive store instance.
+cart.items.push({ id: "pen", price: 2, quantity: 3 });
+console.log(cart.total); // 30
+```
 
-- **value**: The value to check.
+Objects inserted into arrays become reactive stores. Their existing fields can be updated, while their object schema remains sealed.
 
-Returns `true` if the value is a reactive store, otherwise `false`.
+### Form state with derived validation
 
-### `api.is`
+```javascript
+const form = store({
+	email: "",
+	password: "",
+	get valid() {
+		return this.email.includes("@") && this.password.length >= 8;
+	},
+});
 
-The api.is function checks if a given value is a signal.
+form.email = "person@example.com";
+form.password = "very-secret";
+console.log(form.valid); // true
+```
 
-- **value**: The value to check.
+Use an effect or a UI binding to react to `form.valid`; reading it manually always returns the current value.
 
-Returns true if the value is a signal, otherwise false.
+### Shared UI state
 
-### `api.signal`
+```javascript
+const ui = store({
+	theme: "light",
+	sidebar: { open: false },
+	notifications: [],
+});
 
-The `api.signal` function is used to create a reactive signal.
+ui.sidebar.open = true;
+ui.notifications.push({ id: 1, message: "Saved" });
+ui.theme = "dark";
+```
 
-- **value**: The initial value for the signal.
+Create request- or component-specific stores when the state must not be shared. See [SSR and Next.js](#ssr-and-nextjs).
 
-Returns a signal that can be used to create reactive state within the store.
+## API reference
 
-### `api.get`
+### `store(values, proto?)`
 
-The `api.get` function retrieves the current value of a signal.
+Creates and returns a reactive object or array store.
 
-- **signal**: The signal whose value you want to retrieve.
+```javascript
+const state = store({ nested: { value: 1 } });
+state.nested.value = 2;
+```
 
-Returns the current value of the signal.
+Behavior:
 
-### `api.set`
+- Existing object properties become signal-backed accessors.
+- Nested objects and arrays are recursively converted.
+- Existing stores are returned unchanged.
+- Repeated and cyclic references preserve identity.
+- `proto` optionally replaces the new object store's prototype.
+- Primitives, including `null` and `undefined`, are returned unchanged.
+- Class instances, dates, maps, sets, and similar objects are treated as atomic values.
+- Calling `store` for an object or array before configuring the required adapter throws an error.
 
-The `api.set` function updates the value of a signal.
+Object stores have a **sealed schema**. Adding or deleting object properties is unsupported; replace the containing object when its shape must change. Arrays remain structurally mutable.
 
-- **signal**: The signal whose value you want to update.
-- **value**: The new value to set.
+```javascript
+const state = store({ profile: { name: "Ada" } });
 
-Updates the signal with the provided value.
+// Instead of adding a new field to profile:
+state.profile = { name: "Ada", active: true };
+```
 
-## Usage
+### `is(value)`
 
-### Basic Usage
+Returns `true` for a reactive store and `false` for every other value.
 
 ```javascript
-const s = store({ a: 1, b: 2 });
-console.log(s.a); // 1
-s.a = 5;
-console.log(s.a); // 5
+is(state);   // true
+is({});      // false
+is(null);    // false
 ```
 
-You can use the `store` function to create a reactive state object. Assigning a new value to `s.a` will automatically trigger updates wherever `s.a` is used.
+### `state.$property`
 
-### Advanced Usage
+Exposes the underlying signal for a data property, or the underlying memo for a memoized getter.
 
 ```javascript
-const s = store({
-	a: 2,
-	b: 3,
-	get sum() {
-		return this.a + this.b;
-	},
-});
+const state = store({ count: 0 });
 
-console.log(s.sum); // 5
-s.a = 5;
-console.log(s.sum); // 8
+state.$count.value = 2; // Preact signal example
+console.log(state.count); // 2
 ```
 
-Here, you can define getters that automatically compute derived state values, and these getters will update whenever the underlying signals change.
+Aliases are non-enumerable. Getters without `api.memo` do not have a `$` alias. If an input explicitly defines a conflicting key such as `$count`, the user-defined property takes precedence.
+
+### Adapter API
+
+Required operations:
+
+| Operation | Purpose |
+| --- | --- |
+| `api.signal(value)` | Create a signal. |
+| `api.get(signal)` | Read its current value. |
+| `api.set(signal, value)` | Update its value. |
+| `api.is(value)` | Detect an existing signal without misclassifying ordinary functions or objects. |
+
+Optional operations:
+
+| Operation | Purpose |
+| --- | --- |
+| `api.memo(fn)` | Create a lazy computed value. |
+| `api.getMemo(memo)` | Read a memo; defaults to `api.get`. |
+| `api.effect(fn)` | Required by `ustor/react`; must auto-track synchronously and return a cleanup function. |
+
+Without `api.memo`, getters execute on each access and still participate in compatible effects. With `api.memo`, getters are lazy and cached while their dependencies remain unchanged.
 
-### Deeply Nested Structures
+## Arrays
 
-The `store` function can also handle deeply nested objects, converting nested properties into reactive signals:
+Arrays are proxies over their mutable input target. Mutate the returned store, not the original input, to send notifications.
 
 ```javascript
-const s = store({ nested: { deep: { value: 10 } } });
-const deepValue = s.nested.deep.value * 2;
+const state = store({ list: [1, 2, 3] });
 
-console.log(deepValue); // 20
-s.nested.deep.value = 15;
-console.log(s.nested.deep.value) * 2; // 30
+state.list[1] = 5;
+state.list.push(4);
+state.list.splice(0, 1);
+state.list.length = 2;
+delete state.list[0];
 ```
 
-### Arrays and Objects
+Tracked operations include:
 
-This library can handle arrays and objects seamlessly, automatically wrapping array elements with reactivity:
+- Index assignment and whole-array replacement.
+- `push`, `pop`, `shift`, `unshift`, `splice`, `sort`, `reverse`, `fill`, and `copyWithin`.
+- Length changes and `delete`.
+- Iteration, key enumeration, and the `in` operator.
+- Objects inserted by assignment or mutating methods.
+- Sparse arrays and nullish entries.
+
+Each standard mutating method emits at most one notification after it finishes. Deterministic model tests compare randomized mutation sequences against native arrays.
+
+## Supported adapters
+
+The configurations in `adapters.spec.js` are executable documentation and include lifecycle scopes where appropriate.
+
+| Package | Getter support |
+| --- | --- |
+| `@preact/signals-core` | Automatic memoization |
+| `solid-js` | Automatic memoization |
+| `oby` | Automatic memoization |
+| `sinuous/observable` | Automatic memoization |
+| `ulive` | Automatic memoization |
+| `usignal` | Automatic memoization |
+| `@vue/reactivity` | Automatic memoization using `shallowRef` |
+| `alien-signals` | Automatic memoization |
+| `s-js` | Automatic memoization using the provided branded factory |
+| `mobx` | Automatic memoization using shallow observable boxes |
+| `@tanstack/store` | Automatic memoization using the provided value wrapper |
+| `@webreflection/signal` | Automatic memoization |
+| `@webreflection/signals` | Automatic memoization |
+| `@webreflection/alien-signals` | Automatic memoization |
+| `rxjs` | Basic: `BehaviorSubject` values and direct getters |
+| `nanostores` | Basic: atoms and direct getters |
+
+**Basic adapters** support synchronous values, nested objects, arrays, and getters evaluated on access. RxJS and Nanostores do not automatically discover arbitrary getter dependencies, so automatic memoization is not advertised for them.
+
+Adapter-specific notes:
+
+- Vue and MobX use shallow containers to avoid wrapping UStor's proxies twice.
+- TanStack Store treats bare functions as computed values; its tested adapter wraps writable values.
+- S.js has no built-in signal brand; use the tested factory and create memoized stores inside an S.js root.
+- Solid.js, Vue, S.js, and similar libraries may require their own owner/scope lifecycle for short-lived memos.
+
+## Porting any signal library
+
+You normally **do not need to modify UStor's core**. Port a library by translating its synchronous read/write API into four required functions, then add optional memo/effect functions when supported.
+
+### 1. Map the four required operations
+
+Use this template and replace the example method names with your library's API:
 
 ```javascript
-const s = store({ list: [1, 2, 3] });
-const sum = s.list.reduce((acc, item) => acc + item, 0);
+import { store, api } from "ustor";
+import * as library from "your-signal-library";
 
-console.log(sum); // 6
-s.list = [1, 5, 3];
-console.log(s.list.reduce((acc, item) => acc + item, 0)); // 9
-```
+Object.assign(api, {
+	// Create a container that can hold any value.
+	signal: (value) => library.create(value),
+
+	// Return the current value synchronously.
+	get: (signal) => library.read(signal),
+
+	// Store this exact value and notify synchronously.
+	set: (signal, value) => library.write(signal, value),
 
-### Reactivity and Effects
+	// Return true only for signals from this library.
+	is: (value) => library.isSignal(value),
+});
+```
 
-The signal value trigger with effects to track dependencies and automatically re-run whenever dependencies change:
+For a `.value`-based library, the mapping usually looks like this:
 
 ```javascript
-const s = store({ a: 1 });
-let effectValue = 0;
+Object.assign(api, {
+	signal: (value) => library.create(value),
+	get: (signal) => signal.value,
+	set: (signal, value) => { signal.value = value; },
+	is: (value) => value instanceof library.Signal,
+});
+```
+
+For a callable-signal library:
 
-effect(() => {
-	effectValue = s.a * 2;
+```javascript
+Object.assign(api, {
+	signal: (value) => library.create(value),
+	get: (signal) => signal(),
+	set: (signal, value) => signal(value),
+	is: (value) => typeof value === "function" && library.isSignal(value),
 });
+```
 
-console.log(effectValue); // 2
-s.a = 4;
-console.log(effectValue); // 8
+If the setter expects an updater rather than a direct value, adapt it explicitly:
+
+```javascript
+api.set = (signal, value) => signal.setState(() => value);
 ```
 
-## Integration with Solid.js, Preact Signals or any
+### 2. Preserve values without double-wrapping
+
+`api.signal` must be able to store `null`, `undefined`, functions, arrays, objects, and UStor proxies.
+
+- Use a **shallow** signal/ref/box when the library offers one.
+- Do not make the contained object deeply observable a second time.
+- Do not call a function merely because it was stored as a value.
+- If a library interprets a function argument as a computed getter, place the value inside a shallow container or use the tested wrapper pattern from `adapters.spec.js`.
+
+For example, the Vue adapter uses `shallowRef`, and the MobX adapter uses `observable.box(value, { deep: false })`.
 
-This library can be used with Solid.js, Preact Signals, or any other UI framework to provide reactive signals.
+### 3. Make `api.is` a precise brand check
 
-To use Solid.js:
+A broad check can turn ordinary values into signals accidentally. Prefer `instanceof`, a library-provided brand check, or a documented marker.
 
 ```javascript
-import { createSignal } from "solid-js";
+// Risky for callable-signal libraries: ordinary functions are values too.
+api.is = (value) => typeof value === "function"; // Do not use this by itself.
+```
+
+If the library has no brand, create signals through a factory and track them in a `WeakSet`:
+
+```javascript
+const signals = new WeakSet();
+
+api.signal = (value) => {
+	const signal = library.create(value);
+	signals.add(signal);
+	return signal;
+};
 
-api.signal = createSignal;
-api.get = (v) => v?.[0]();
-api.set = (signal, v) => signal?.[1](v);
-api.is = (v) =>
-	(Array.isArray(v) &&
-		typeof v[0] === "function" &&
-		typeof v[1] === "function") ||
-	v?.[0]?.name?.includes("readSignal");
+api.is = (value) => signals.has(value);
 ```
 
-To use Preact Signals, usignal, ulive, etc:
+Create external signals through `api.signal` when using this approach. The S.js configuration in `adapters.spec.js` demonstrates it.
+
+### 4. Add memoization only when dependencies are automatic
+
+If the library can compute a value by automatically tracking signals read inside `fn`, add:
 
 ```javascript
-import { signal } from "@preact/signals-core";
+Object.assign(api, {
+	memo: (fn) => library.computed(fn),
+	getMemo: (memo) => library.read(memo),
+});
+```
+
+The memo may be lazy or eager, but it must invalidate when any dependency changes, including conditional dependencies.
 
-api.signal = signal;
-api.get = (v) => v?.value;
-api.set = (signal, v) => (signal.value = v);
-api.is = (v) => v?.peek;
+If the library requires an explicit dependency list—as with RxJS or Nanostores—**omit `memo` and `getMemo`**. UStor then uses direct getters evaluated on access. Do not emulate automatic memoization incorrectly.
+
+### 5. Add effects for React integration only when compatible
+
+`ustor/react` requires this additional contract:
+
+```javascript
+api.effect = (fn) => {
+	const dispose = library.effect(fn);
+	return () => dispose(); // Always return a cleanup function.
+};
 ```
 
-To use any signal library
+A compatible effect must:
+
+1. Run `fn` and automatically track its synchronous signal reads.
+2. Rerun synchronously after a dependency changes.
+3. Return a cleanup function, or be wrapped in an owner/root that provides one.
+
+The core store does not require `api.effect`. Basic adapters without automatic dependency discovery can still provide ordinary state reads and writes.
+
+### 6. Configure once and manage lifecycle
+
+Configure `api` before creating stores and keep the same implementation for their lifetime. If your library requires an owner, scope, root, or disposer for memos/effects, create short-lived stores in that lifecycle and dispose them with their owner.
+
+### 7. Validate the adapter
+
+This Node script checks the required behavior, function preservation, nested updates, arrays, and optional memoization:
 
 ```javascript
-import ... from "...";
+import assert from "node:assert/strict";
+import { store, api } from "ustor";
+// Configure your adapter before these assertions.
+
+const external = api.signal(1);
+const state = store({
+	value: external,
+	nested: { count: 2 },
+	list: [1, 2],
+	fn: () => 7,
+	get total() {
+		return this.nested.count + this.list.reduce((sum, value) => sum + value, 0);
+	},
+});
+
+assert.equal(state.value, 1);
+assert.equal(state.$value, external);
+assert.equal(state.fn(), 7); // The function remains a value.
+
+state.value = 3;
+assert.equal(api.get(external), 3);
+
+state.nested.count = 4;
+assert.equal(state.total, 7);
+
+state.list.push(4);
+assert.equal(state.total, 11);
+
+state.list[0] = 5;
+assert.equal(state.total, 15);
+
+if (api.memo) {
+	assert.equal((api.getMemo || api.get)(state.$total), 15);
+}
+```
+
+A production-quality adapter should also verify:
+
+- Whole-array replacement, deletion, and length changes.
+- Conditional memo dependencies and no-op writes.
+- Effect cleanup and behavior under nested/batched updates.
+- React StrictMode and unmount behavior when used with `ustor/react`.
+- Owner/scope disposal and long-running memory behavior.
+- The library's ESM and CommonJS entry points in your target bundler.
+
+For working examples, copy the closest configuration from `adapters.spec.js`, then run:
+
+```bash
+npm test
+npm run test:coverage
+npm run profile
+```
+
+## React
+
+Install React and import the optional hooks:
+
+```bash
+npm install react
+```
+
+```jsx
+import { useSignal, useStore } from "ustor/react";
+
+// Uses the Preact configuration from Quickstart, including api.effect.
+const state = store({ count: 1, items: [1, 2] });
+const selectTotal = () => state.items.reduce((sum, value) => sum + value, 0);
+
+export function Counter() {
+	const count = useSignal(state.$count);
+	const total = useStore(selectTotal);
+
+	return (
+		<button onClick={() => { state.count++; state.items.push(state.count); }}>
+			{count} / {total}
+		</button>
+	);
+}
+```
+
+- `useSignal(signal)` subscribes to one `$property` signal.
+- `useStore(selector)` tracks all compatible signal reads in the selector, including array versions.
+- Selectors must return a primitive or stable reference, not a fresh object on every read.
+- Keep selector functions stable with `useCallback` when they are created inside a component.
+- React is an optional peer dependency and is excluded from the core bundle.
+- StrictMode and unmount cleanup are tested.
+
+Plain property reads do not schedule React renders by themselves; use the hooks or another React binding.
+
+## SSR and Next.js
+
+Yes. `useStore` and `useSignal` provide a server snapshot through `useSyncExternalStore`. Server rendering creates no effects; subscriptions start on the client.
+
+The test suite verifies:
+
+- Server rendering without `api.effect`.
+- Independent per-request stores.
+- Hydration without markup mismatches.
+- Reactive updates after hydration.
+
+### Next.js App Router example
+
+Use the hooks in a **Client Component**. Create request- or component-owned state instead of exporting a request-specific singleton.
+
+```jsx
+"use client";
+
+import { useCallback, useState } from "react";
+import { store } from "ustor";
+import { useSignal, useStore } from "ustor/react";
+// Import your shared adapter configuration once:
+// import "@/lib/ustor-setup";
+
+export default function Counter({ initialCount }) {
+	const [state] = useState(() => store({
+		count: initialCount,
+		items: [1, 2],
+	}));
+	const selectTotal = useCallback(
+		() => state.items.reduce((sum, value) => sum + value, 0),
+		[state],
+	);
+	const count = useSignal(state.$count);
+	const total = useStore(selectTotal);
+
+	return (
+		<button onClick={() => { state.count++; state.items.push(1); }}>
+			{count} / {total}
+		</button>
+	);
+}
+```
+
+```jsx
+// app/page.jsx
+import Counter from "./Counter";
+
+export default function Page() {
+	return <Counter initialCount={1} />;
+}
+```
+
+SSR requirements:
+
+1. Use `"use client"` for components that call the hooks.
+2. Pass the same serializable initial props during server rendering and hydration.
+3. Do not mutate the rendered state between its server snapshot and initial hydration.
+4. Do not store request-specific data in a module-level singleton shared by server requests.
+5. UStor does not provide a dehydration format. Serialize and restore initial data with your framework when needed.
+6. Configure `api.effect` for client hydration even though it is not used during server rendering.
+
+The repository tests use `react-dom/server` and `hydrateRoot`, the same underlying React SSR primitives used by Next.js Client Components.
+
+## TypeScript
 
-api.signal = ...;
-api.get = ...;
-api.set = (signal, value) => ...;
-api.is = (v) => ...;
+Declarations are included for both entry points; no separate `@types/ustor` package is needed.
+
+```typescript
+import { store } from "ustor";
+import { useStore } from "ustor/react";
 
 const state = store({
-	count: 0
+	count: 1,
+	nested: { text: "hello" },
+	list: [1, 2],
+	get double() { return this.count * 2; },
 });
+
+state.count = 2;             // valid
+// state.count = "invalid";  // TypeScript error
+
+const doubled: number = state.double;
+const text: string = state.nested.text;
+const total = useStore(() => state.list.reduce((sum, value) => sum + value, 0));
+```
+
+Exported type utilities:
+
+- `SignalApi<Signal, Memo>` for custom adapters.
+- `Store<T>` for reactive store inference.
+- `SignalValue<Signal>` for React signal-value inference.
+
+Run the repository's strict compile-time tests with:
+
+```bash
+npm run typecheck
+```
+
+## Profiling and memory analysis
+
+The profiler uses Preact Signals and measures:
+
+- High-frequency memoized property updates.
+- Batched property updates.
+- Bounded array mutation workloads.
+- Repeated store/effect creation, updates, and disposal with heap/RSS samples.
+
+Run a short smoke profile:
+
+```bash
+npm run profile:smoke
+```
+
+Run the default 30-second memory profile:
+
+```bash
+npm run profile
+```
+
+Run a longer custom profile:
+
+```bash
+npm run profile -- --updates=1000000 --array-updates=100000 --seconds=60 --sample-ms=1000
+```
+
+Write machine-readable output:
+
+```bash
+npm run --silent profile -- --json --seconds=30 > profile.json
+```
+
+Profiling guidelines:
+
+- Run with the same Node version and workload characteristics as production.
+- Compare several samples after warm-up and forced GC, not one heap reading.
+- A flat retained-heap trend is more useful than a single delta.
+- RSS can grow early and plateau because of allocator behavior; RSS alone does not prove a leak.
+- The CI smoke profile checks that the profiler remains runnable, not that every workload is leak-free.
+- Repeat equivalent profiling with the adapter and application workload you actually deploy.
+
+## Production notes
+
+- Use one adapter per UStor module instance and keep it for the lifetime of existing stores.
+- Dispose adapter owners/scopes and UI subscriptions for short-lived stores.
+- Test your actual browser, bundler, SSR, and hydration path.
+- Stress-test application-specific update patterns and long-running memory usage.
+- Use basic RxJS/Nanostores adapters only where their direct-getter semantics are sufficient.
+- Keep runtime and development artifacts separate; `dist` and declarations are the only published implementation files.
+
+### Release checklist
+
+The repository already checks unit and adapter behavior, TypeScript declarations, React, SSR/hydration, package formats, bundle size, coverage, and dependency audit status.
+
+Before publishing a production release:
+
+1. **Choose a new version and write release notes.** The changes since the original `0.1.0` include observable behavior changes. Do not publish them as the same version; use an appropriate new version and document getter, sealed-object, array-proxy, and packaging behavior.
+2. **Test the packed artifact in a clean consumer application.** Run your real bundler and framework against the tarball rather than only against repository source.
+3. **Exercise your production SSR path.** The generic React SSR primitives are tested, but a full Next.js or other framework application should verify its own rendering, dehydration, and hydration flow.
+4. **Run target-browser and production-adapter checks.** Repeat performance and long-running memory profiling with the adapter and workload you deploy.
+5. **Review the release artifact.** Confirm `npm pack --dry-run`, `npm audit`, the package entry points, declaration files, license, and version before tagging or publishing.
+
+## Development
+
+```bash
+npm ci
+npm test                 # build, type tests, unit/adapter/React/SSR tests, package smoke tests
+npm run typecheck        # strict TypeScript declaration tests
+npm run test:coverage    # enforced 100% runtime coverage
+npm run test:watch
+npm run profile:smoke
+npm run build
 ```
 
-The library provides a unified API to work with different reactive systems, allowing you to switch between Solid.js, Preact Signals, or any other UI framework easily.
+The core size budget is enforced at 2 KiB minified and 1 KiB gzipped. `dist` is generated during build/prepack; declarations are published from `types/`.
 
-### License
+## License
 
-This library is provided "as-is" under the MIT license. Feel free to use, modify, and distribute it in your projects.
+[MIT](./LICENSE)
 
-### Thanks and Inspiration
+## Thanks and inspiration
 
-- **[dy](https://github.com/dy)**
+- [dy](https://github.com/dy)