opshot 0.1.0 → 0.2.1

package/README.md

@@ -2,12 +2,7 @@
 
 # opshot
 
-Plain-object state for React: mutate it directly, re-render only the components that read what changed, and track every change operation.
-
-- **Self-contained**: a state carries its data, its methods, and its own subscription; pass it around like any object.
-- **Reactive reads**: components read plain properties, and reads are tracked per component: a component re-renders only when a property it read changes.
-- **Safe mutation**: write by mutating the actual object directly inside `mutate`.
-- **Ops events**: every mutation emits its changes as `{ do, undo }` JSON Patch pairs, ready for history, sync, and persistence.
+Mutable state for React, with re-render for only the components that read what changed. (It's [valtio](https://github.com/pmndrs/valtio), but not a footgun.)
 
 ## Install
 
@@ -15,29 +10,81 @@ Plain-object state for React: mutate it directly, re-render only the components
 npm install opshot
 ```
 
-## Quick start
+## Mutable state
+
+React state is immutable: changing one field means spreading the old object into a new one.
+
+```tsx
+const [user, setUser] = useState({ name: "Ada", age: 36 });
+
+setUser((prev) => ({ ...prev, age: 37 }));
+```
+
+opshot state is mutable: you assign the field.
+
+```tsx
+const user = useTrackedState({ name: "Ada", age: 36 });
+
+user.mutate((mutable) => (mutable.age = 37));
+```
+
+## Bounded re-renders
+
+React re-renders a component and its children when its state changes.
 
 ```tsx
-import { useCreateState } from "opshot/react";
+interface User {
+	name: string;
+	age: number;
+}
 
-const Counter = () => {
-	const counter = useCreateState({ count: 0 });
+const Parent = () => {
+	const [user, setUser] = useState<User>({ name: "Ada", age: 36 });
 
-	// Mutate the object directly: assignments, push, delete all work.
-	const increment = () => counter.op.mutate((proxy) => proxy.count++);
+	const birthday = () => setUser((prev) => ({ ...prev, age: prev.age + 1 }));
 
-	return <button onClick={increment}>{counter.count}</button>;
+	// A click re-renders Parent and Child.
+	return (
+		<>
+			<button onClick={birthday}>+</button>
+			<Child user={user} />
+		</>
+	);
 };
+
+const Child = ({ user }: { user: User }) => <p>{user.age}</p>;
 ```
 
-## Creating state
+opshot re-renders only what read the change. Wrap a child in `retrack` and it subscribes to the fields it reads. **Where the mutation happens doesn't matter** — here Parent writes, and only Child re-renders, because renders follow reads, not writes.
+
+```tsx
+const Parent = () => {
+	const user = useTrackedState<User>({ name: "Ada", age: 36 });
+
+	const birthday = () => user.mutate((mutable) => mutable.age++);
+
+	// A click re-renders only Child.
+	return (
+		<>
+			<button onClick={birthday}>+</button>
+			<Child user={user} />
+		</>
+	);
+};
+
+const Child = retrack<{ user: State<User> }>(({ user }) => <p>{user.age}</p>);
+```
+
+This is how you optimize re-rendering across your component tree: place `retrack` boundaries where you want re-renders contained, and each boundary re-renders only when a field it read changes. `useTrackedState` is a boundary itself.
+
+## Creating State
 
 ```tsx
 import { ref } from "opshot";
-import { useCreateState } from "opshot/react";
+import { useTrackedState } from "opshot/react";
 
 const Player = () => {
-	const player = useCreateState((mutate, get) => ({
+	const player = useTrackedState((mutate, get) => ({
 		position: 0,
 
 		// ref() keeps a value out of reactivity and ops.
@@ -47,7 +94,7 @@ const Player = () => {
 		seek: (position: number) => {
 			get().element.currentTime = position;
 
-			mutate((proxy) => (proxy.position = position));
+			mutate((mutable) => (mutable.position = position));
 		},
 	}));
 
@@ -55,16 +102,16 @@ const Player = () => {
 };
 ```
 
-## state.op
+## Tracked State
 
-Everything opshot attaches lives under one reserved key, `op`.
+Everything opshot attaches lives under two reserved keys, `mutate` and `op`.
 
 ```ts
 // The write path. An optional second argument is passed to every subscriber.
-counter.op.mutate((proxy) => {}, { transactionKey: "drag" });
+counter.mutate((mutable) => mutable.count++, { transactionKey: "drag" });
 
 // Hears every op this state emits; returns an unsubscribe.
-const unsubscribe = counter.op.subscribe((state, ops, options) => {
+const unsubscribe = counter.op.subscribe((state, ops, meta) => {
 	// ...
 });
 
@@ -78,13 +125,13 @@ counter.op.isMutating;
 counter.op.unwrap();
 
 // The underlying valtio proxy, typed object: an escape hatch.
-counter.op.proxy;
+counter.op.unsafeMutable;
 ```
 
 ## Ops
 
 ```ts
-const unsubscribe = counter.op.subscribe((state, ops, options) => {
+const unsubscribe = counter.op.subscribe((state, ops, meta) => {
 	// state: the snapshot these ops produced
 	// ops: [{
 	//   do:   { op: "replace", path: "/count", value: 1 },
@@ -99,75 +146,71 @@ A subscriber must not write to the state it subscribes to; writing to a differen
 
 Ops cost nothing until someone listens: a state with no subscribers, on itself or its group, skips computing them entirely.
 
-## Groups
+## Meta
 
-A group creates states and hears every op from the states it created: one stream for history, sync, and persistence.
+`mutate`'s optional second argument is delivered to every subscriber alongside the ops.
+
+To type it, declare a meta token once and pass it in.
 
 ```tsx
 import { useEffect } from "react";
-import { useCreateGroup, useCreateState } from "opshot/react";
+import { createMeta } from "opshot";
+import { useTrackedState } from "opshot/react";
+
+interface DocumentMeta {
+	replay?: boolean;
+}
+
+// Declared once, at module scope.
+const documentMeta = createMeta<DocumentMeta>();
 
 const Editor = () => {
-	// A lifetime-stable group.
-	const group = useCreateGroup();
+	const doc = useTrackedState({ title: "Untitled" }, documentMeta);
 
-	// Created through the group, so its ops reach the group's subscribers.
-	const doc = useCreateState({ items: new Array<string>() }, group);
+	// A history replaying an undone op marks the write, so recorders can tell it apart.
+	// The meta argument is typed DocumentMeta.
+	const undo = () => doc.mutate((mutable) => (mutable.title = "Untitled"), { replay: true });
 
 	useEffect(
 		() =>
-			// Fires for doc and every other state the group created.
-			group.subscribe((state, ops, options) => {
+			// The subscriber's meta parameter is typed DocumentMeta.
+			doc.op.subscribe((state, ops, meta) => {
+				// A recorder skips its own replays.
+				if (meta.replay) return;
+
 				// ...
 			}),
-		[group],
+		[doc.op],
 	);
 
 	// ...
 };
 ```
 
-## resnapshot
-
-A component re-renders when a property it read changes. Reads belong to the nearest subscribed component above them: `useCreateState` subscribes the component that created the state, and `resnapshot` subscribes the component it wraps.
+## Groups
 
-This is a lever for bounding re-renders. Here `CounterButton` is plain, so its `count` read belongs to `App`, and every click re-renders `App` and everything under it:
+A group creates states and hears every op from the states it created: one stream for history, sync, and persistence.
 
 ```tsx
-import type { State } from "opshot";
-import { useCreateState } from "opshot/react";
+import { useEffect } from "react";
+import { useGroup, useTrackedState } from "opshot/react";
 
-interface Counter {
-	title: string;
-	count: number;
-}
+const Editor = () => {
+	// A lifetime-stable group.
+	const group = useGroup();
 
-// Every click re-renders App and its whole subtree.
-const App = () => {
-	const counter = useCreateState<Counter>({ title: "Hits", count: 0 });
+	// Created through the group, so its ops reach the group's subscribers.
+	const doc = useTrackedState({ items: new Array<string>() }, group);
 
-	return (
-		<>
-			<h1>{counter.title}</h1>
-			<CounterButton counter={counter} />
-		</>
+	useEffect(
+		() =>
+			// Fires for doc and every other state the group created.
+			group.subscribe((state, ops, meta) => {
+				// ...
+			}),
+		[group],
 	);
-};
 
-const CounterButton = ({ counter }: { counter: State<Counter> }) => (
-	<button onClick={() => counter.op.mutate((proxy) => proxy.count++)}>{counter.count}</button>
-);
-```
-
-Wrapping `CounterButton` in `resnapshot` subscribes it, so its `count` read becomes its own. A click now re-renders `CounterButton` alone:
-
-```tsx
-import { resnapshot } from "opshot/react";
-
-// A click re-renders only CounterButton. A title change would still re-render App.
-const CounterButton = resnapshot<{ counter: State<Counter> }>(({ counter }) => (
-	<button onClick={() => counter.op.mutate((proxy) => proxy.count++)}>{counter.count}</button>
-));
+	// ...
+};
 ```
-
-Subscribed components re-render independently: had `App` also read `count`, both would re-render.

package/dist/index.d.ts

@@ -19,29 +19,38 @@ interface Op {
 }
 declare function diffSnapshots(before: unknown, after: unknown): Array<Op>;
 
-type MutateOptions = Record<string, unknown>;
-type Mutate<T extends object> = (callback: (proxy: T) => void, options?: MutateOptions) => void;
-type StateListener<T extends object> = (state: State<T>, ops: Array<Op>, options: MutateOptions) => void;
-interface OpshotHandle<T extends object> {
-    readonly proxy: object;
+type MetaRecord = Record<string, unknown>;
+declare const metaIn: unique symbol;
+interface Meta<In extends object = MetaRecord, Out extends object = MetaRecord> {
+    readonly defaults?: Out;
+    readonly [metaIn]?: (value: In) => void;
+}
+type Mutate<T extends object, In extends object = MetaRecord> = (callback: (mutable: T) => void, ...meta: {} extends In ? [meta?: In] : [meta: In]) => void;
+type StateListener<T extends object, In extends object = MetaRecord, Out extends object = MetaRecord> = (state: State<T, In, Out>, ops: Array<Op>, meta: Out) => void;
+interface OpshotHandle<T extends object, In extends object = MetaRecord, Out extends object = MetaRecord> {
+    readonly unsafeMutable: object;
     readonly isMutating: boolean;
-    readonly mutate: Mutate<T>;
-    readonly subscribe: (listener: StateListener<T>) => () => void;
+    readonly subscribe: (listener: StateListener<T, In, Out>) => () => void;
     readonly isSameState: (other: unknown) => boolean;
     readonly unwrap: () => Snapshot<T>;
 }
-type State<T extends object> = Snapshot<T> & {
-    readonly op: OpshotHandle<T>;
+type State<T extends object, In extends object = MetaRecord, Out extends object = MetaRecord> = Snapshot<T> & {
+    readonly mutate: Mutate<T, In>;
+    readonly op: OpshotHandle<T, In, Out>;
 };
-type DefineCallback<T extends object> = (mutate: Mutate<T>, get: () => State<T>) => T;
-type Define<T extends object> = DefineCallback<T> | T;
+type DefineCallback<T extends object, In extends object = MetaRecord, Out extends object = MetaRecord> = (mutate: Mutate<T, In>, get: () => State<T, In, Out>) => T;
+type Define<T extends object, In extends object = MetaRecord, Out extends object = MetaRecord> = DefineCallback<T, In, Out> | T;
+declare function createMeta<M extends object>(): Meta<M, M>;
+declare function createMeta<M extends object>(defaults: M): Meta<Partial<M>, M>;
 declare function createState<T extends object>(define: Define<T>): State<T>;
+declare function createState<T extends object, In extends object, Out extends object>(define: Define<T, In, Out>, meta: Meta<In, Out>): State<T, In, Out>;
 declare function isState(value: unknown): value is State<object>;
 
-interface Group {
-    createState<T extends object>(define: Define<T>): State<T>;
-    subscribe(listener: StateListener<object>): () => void;
+interface Group<In extends object = MetaRecord, Out extends object = MetaRecord> {
+    createState<T extends object>(define: Define<T, In, Out>): State<T, In, Out>;
+    subscribe(listener: StateListener<object, In, Out>): () => void;
 }
 declare function createGroup(): Group;
+declare function createGroup<In extends object, Out extends object>(meta: Meta<In, Out>): Group<In, Out>;
 
-export { type Define, type DefineCallback, type Group, type Mutate, type MutateOptions, type Op, type OpshotHandle, type PatchOperation, type State, type StateListener, createGroup, createState, diffSnapshots, isState };
+export { type Define, type DefineCallback, type Group, type Meta, type MetaRecord, type Mutate, type Op, type OpshotHandle, type PatchOperation, type State, type StateListener, createGroup, createMeta, createState, diffSnapshots, isState };

package/dist/index.js

@@ -66,11 +66,16 @@ function diffSnapshots(before, after) {
 
 // src/createState.ts
 var stateBrand = /* @__PURE__ */ Symbol.for("opshot.state");
+var metaBrand = /* @__PURE__ */ Symbol.for("opshot.meta");
 var hasOwn = (value, key) => Object.hasOwn(value, key);
-function createState(define) {
-  return createGroupState(define);
+function createMeta(defaults) {
+  const token = defaults === void 0 ? { [metaBrand]: true } : { defaults, [metaBrand]: true };
+  return token;
 }
-function createGroupState(define, groupListeners) {
+function createState(define, meta) {
+  return createGroupState(define, void 0, meta);
+}
+function createGroupState(define, groupListeners, metaToken) {
   const callback = typeof define === "function" ? define : () => define;
   const listeners = /* @__PURE__ */ new Set();
   const created = {};
@@ -80,7 +85,8 @@ function createGroupState(define, groupListeners) {
     return proxied;
   };
   const get = () => snapshot(requireProxy());
-  const mutate = (callback2, options = {}) => {
+  const mutate = (callback2, ...metaArgs) => {
+    const [meta] = metaArgs;
     const proxied = requireProxy();
     if (handle.isMutating) throw new Error("opshot: nested mutate on the same state");
     handle.isMutating = true;
@@ -95,8 +101,9 @@ function createGroupState(define, groupListeners) {
     if (listeners.size === 0 && (groupListeners?.size ?? 0) === 0) return;
     const ops = diffSnapshots(before, after);
     if (ops.length === 0) return;
-    for (const listener of [...groupListeners ?? []]) listener(after, ops, options);
-    for (const listener of [...listeners]) listener(after, ops, options);
+    const emittedMeta = metaToken?.defaults !== void 0 ? { ...metaToken.defaults, ...meta } : meta ?? {};
+    for (const listener of [...groupListeners ?? []]) listener(after, ops, emittedMeta);
+    for (const listener of [...listeners]) listener(after, ops, emittedMeta);
   };
   const subscribe = (listener) => {
     listeners.add(listener);
@@ -106,17 +113,20 @@ function createGroupState(define, groupListeners) {
   };
   const isSameState = (other) => isState(other) && other.op === handle;
   const unwrap = () => {
-    const { op, ...rest } = get();
+    const { op, mutate: mutate2, ...rest } = get();
     return rest;
   };
   const literal = callback(mutate, get);
-  if (Object.hasOwn(literal, "op")) throw new Error('opshot: "op" is a reserved key on a state');
+  for (const key of ["op", "mutate"]) {
+    if (Object.hasOwn(literal, key)) throw new Error(`opshot: "${key}" is a reserved key on a state`);
+  }
   const base = Object.create(Reflect.getPrototypeOf(literal));
   Object.defineProperties(base, Object.getOwnPropertyDescriptors(literal));
-  const handle = { proxy: base, isMutating: false, mutate, subscribe, isSameState, unwrap, [stateBrand]: true };
+  const handle = { unsafeMutable: base, isMutating: false, subscribe, isSameState, unwrap, [stateBrand]: true };
   Object.defineProperty(base, "op", { value: ref(handle), enumerable: true, writable: false, configurable: false });
+  Object.defineProperty(base, "mutate", { value: mutate, enumerable: true, writable: false, configurable: false });
   created.proxied = proxy(base);
-  handle.proxy = created.proxied;
+  handle.unsafeMutable = created.proxied;
   return get();
 }
 function isState(value) {
@@ -127,11 +137,11 @@ function isState(value) {
 }
 
 // src/createGroup.ts
-function createGroup() {
+function createGroup(meta) {
   const listeners = /* @__PURE__ */ new Set();
   return {
     createState(define) {
-      return createGroupState(define, listeners);
+      return createGroupState(define, listeners, meta);
     },
     subscribe(listener) {
       listeners.add(listener);
@@ -142,4 +152,4 @@ function createGroup() {
   };
 }
 
-export { createGroup, createState, diffSnapshots, isState };
+export { createGroup, createMeta, createState, diffSnapshots, isState };

package/dist/react.d.ts

@@ -1,9 +1,11 @@
 import { FC } from 'react';
-import { Group, Define, State } from './index.js';
+import { Group, Meta, Define, State } from './index.js';
 import 'valtio/vanilla';
 
-declare function resnapshot<P extends object>(component: FC<P>): FC<P>;
-declare const useCreateGroup: () => Group;
-declare const useCreateState: <T extends object>(define: Define<T>, group?: Group) => State<T>;
+declare function retrack<P extends object>(component: FC<P>): FC<P>;
+declare function useGroup(): Group;
+declare function useGroup<In extends object, Out extends object>(meta: Meta<In, Out>): Group<In, Out>;
+declare function useTrackedState<T extends object>(define: Define<T>): State<T>;
+declare function useTrackedState<T extends object, In extends object, Out extends object>(define: Define<T, In, Out>, groupOrMeta: Group<In, Out> | Meta<In, Out>): State<T, In, Out>;
 
-export { resnapshot, useCreateGroup, useCreateState };
+export { retrack, useGroup, useTrackedState };

package/dist/react.js

@@ -1,6 +1,6 @@
 import { isChanged, createProxy } from 'proxy-compare';
 import { memo, useState, useMemo, useRef, useCallback, useSyncExternalStore, useLayoutEffect } from 'react';
-import { unstable_getInternalStates, snapshot, subscribe, ref, proxy } from 'valtio/vanilla';
+import { unstable_getInternalStates, ref, proxy, snapshot, subscribe } from 'valtio/vanilla';
 
 // src/react.tsx
 var { refSet } = unstable_getInternalStates();
@@ -67,11 +67,13 @@ function diffSnapshots(before, after) {
 
 // src/createState.ts
 var stateBrand = /* @__PURE__ */ Symbol.for("opshot.state");
+var metaBrand = /* @__PURE__ */ Symbol.for("opshot.meta");
 var hasOwn = (value, key) => Object.hasOwn(value, key);
-function createState(define) {
-  return createGroupState(define);
+function isMeta(value) {
+  if (typeof value !== "object" || value === null || !hasOwn(value, metaBrand)) return false;
+  return value[metaBrand] === true;
 }
-function createGroupState(define, groupListeners) {
+function createGroupState(define, groupListeners, metaToken) {
   const callback = typeof define === "function" ? define : () => define;
   const listeners = /* @__PURE__ */ new Set();
   const created = {};
@@ -81,7 +83,8 @@ function createGroupState(define, groupListeners) {
     return proxied;
   };
   const get = () => snapshot(requireProxy());
-  const mutate = (callback2, options = {}) => {
+  const mutate = (callback2, ...metaArgs) => {
+    const [meta] = metaArgs;
     const proxied = requireProxy();
     if (handle.isMutating) throw new Error("opshot: nested mutate on the same state");
     handle.isMutating = true;
@@ -96,8 +99,9 @@ function createGroupState(define, groupListeners) {
     if (listeners.size === 0 && (groupListeners?.size ?? 0) === 0) return;
     const ops = diffSnapshots(before, after);
     if (ops.length === 0) return;
-    for (const listener of [...groupListeners ?? []]) listener(after, ops, options);
-    for (const listener of [...listeners]) listener(after, ops, options);
+    const emittedMeta = metaToken?.defaults !== void 0 ? { ...metaToken.defaults, ...meta } : meta ?? {};
+    for (const listener of [...groupListeners ?? []]) listener(after, ops, emittedMeta);
+    for (const listener of [...listeners]) listener(after, ops, emittedMeta);
   };
   const subscribe = (listener) => {
     listeners.add(listener);
@@ -107,17 +111,20 @@ function createGroupState(define, groupListeners) {
   };
   const isSameState = (other) => isState(other) && other.op === handle;
   const unwrap = () => {
-    const { op, ...rest } = get();
+    const { op, mutate: mutate2, ...rest } = get();
     return rest;
   };
   const literal = callback(mutate, get);
-  if (Object.hasOwn(literal, "op")) throw new Error('opshot: "op" is a reserved key on a state');
+  for (const key of ["op", "mutate"]) {
+    if (Object.hasOwn(literal, key)) throw new Error(`opshot: "${key}" is a reserved key on a state`);
+  }
   const base = Object.create(Reflect.getPrototypeOf(literal));
   Object.defineProperties(base, Object.getOwnPropertyDescriptors(literal));
-  const handle = { proxy: base, isMutating: false, mutate, subscribe, isSameState, unwrap, [stateBrand]: true };
+  const handle = { unsafeMutable: base, isMutating: false, subscribe, isSameState, unwrap, [stateBrand]: true };
   Object.defineProperty(base, "op", { value: ref(handle), enumerable: true, writable: false, configurable: false });
+  Object.defineProperty(base, "mutate", { value: mutate, enumerable: true, writable: false, configurable: false });
   created.proxied = proxy(base);
-  handle.proxy = created.proxied;
+  handle.unsafeMutable = created.proxied;
   return get();
 }
 function isState(value) {
@@ -128,11 +135,11 @@ function isState(value) {
 }
 
 // src/createGroup.ts
-function createGroup() {
+function createGroup(meta) {
   const listeners = /* @__PURE__ */ new Set();
   return {
     createState(define) {
-      return createGroupState(define, listeners);
+      return createGroupState(define, listeners, meta);
     },
     subscribe(listener) {
       listeners.add(listener);
@@ -150,7 +157,7 @@ function shouldTraverse(value) {
   const prototype = Object.getPrototypeOf(value);
   return prototype === Object.prototype || prototype === null;
 }
-function findSnapshotPaths(value, path = [], paths = []) {
+function findStatePaths(value, path = [], paths = []) {
   if (isState(value)) {
     paths.push(path);
     return paths;
@@ -158,12 +165,12 @@ function findSnapshotPaths(value, path = [], paths = []) {
   if (!shouldTraverse(value)) return paths;
   if (Array.isArray(value)) {
     value.forEach((item, index) => {
-      findSnapshotPaths(item, [...path, index], paths);
+      findStatePaths(item, [...path, index], paths);
     });
   } else {
     for (const [key, propertyValue] of Object.entries(value)) {
       if (key === "children") continue;
-      findSnapshotPaths(propertyValue, [...path, key], paths);
+      findStatePaths(propertyValue, [...path, key], paths);
     }
   }
   return paths;
@@ -191,10 +198,10 @@ function setAtPath(object, path, value) {
   return { ...object, [head]: updated };
 }
 var targetCache = /* @__PURE__ */ new WeakMap();
-function useResnapshotAll(snapshots) {
+function useRetrackAll(states) {
   const lastRendered = useRef([]);
   const lastReturned = useRef([]);
-  const nextProxies = snapshots.map((snap) => snap.op.proxy);
+  const nextProxies = states.map((state) => state.op.unsafeMutable);
   const [proxies, setProxies] = useState(nextProxies);
   const isStale = proxies.length !== nextProxies.length || proxies.some((proxied, index) => proxied !== nextProxies[index]);
   if (isStale) setProxies(nextProxies);
@@ -228,40 +235,45 @@ function useResnapshotAll(snapshots) {
     },
     [proxies, trackings]
   );
-  const freshSnapshots = useSyncExternalStore(subscribe$1, getSnapshot);
+  const freshStates = useSyncExternalStore(subscribe$1, getSnapshot);
   useLayoutEffect(() => {
-    lastRendered.current = freshSnapshots;
+    lastRendered.current = freshStates;
   });
   const trackedSnapshots = useMemo(
-    () => freshSnapshots.map((snap, index) => {
+    () => freshStates.map((snap, index) => {
       const tracking = trackings[index];
       if (!tracking) return snap;
       return createProxy(snap, tracking.affected, tracking.proxyCache, targetCache);
     }),
-    [freshSnapshots, trackings]
+    [freshStates, trackings]
   );
-  return isStale ? snapshots : trackedSnapshots;
+  return isStale ? states : trackedSnapshots;
 }
-function resnapshot(component) {
+function retrack(component) {
   const componentName = component.displayName ?? component.name;
-  const Resnapshotted = (props) => {
-    const snapshotPaths = useMemo(() => findSnapshotPaths(props), [props]);
-    const staleSnapshots = useMemo(() => snapshotPaths.map((path) => getAtPath(props, path)).filter(isState), [props, snapshotPaths]);
-    const freshSnapshots = useResnapshotAll(staleSnapshots);
+  const Retracked = (props) => {
+    const snapshotPaths = useMemo(() => findStatePaths(props), [props]);
+    const staleStates = useMemo(() => snapshotPaths.map((path) => getAtPath(props, path)).filter(isState), [props, snapshotPaths]);
+    const freshStates = useRetrackAll(staleStates);
     const freshProps = useMemo(() => {
-      if (freshSnapshots === staleSnapshots) return props;
-      return snapshotPaths.reduce((acc, path, index) => setAtPath(acc, path, freshSnapshots[index]), props);
-    }, [props, snapshotPaths, staleSnapshots, freshSnapshots]);
+      if (freshStates === staleStates) return props;
+      return snapshotPaths.reduce((acc, path, index) => setAtPath(acc, path, freshStates[index]), props);
+    }, [props, snapshotPaths, staleStates, freshStates]);
     return component(freshProps);
   };
-  Resnapshotted.displayName = `resnapshot(${componentName === "" ? "Anonymous" : componentName})`;
-  return memo(Resnapshotted);
+  Retracked.displayName = `retrack(${componentName === "" ? "Anonymous" : componentName})`;
+  return memo(Retracked);
+}
+function useGroup(meta) {
+  return useState(() => meta === void 0 ? createGroup() : createGroup(meta))[0];
 }
-var useCreateGroup = () => useState(() => createGroup())[0];
-var useCreateState = (define, group) => {
-  const created = useState(() => group ? group.createState(define) : createState(define))[0];
-  const [fresh] = useResnapshotAll([created]);
+function useTrackedState(define, groupOrMeta) {
+  const created = useState(() => {
+    if (groupOrMeta !== void 0 && !isMeta(groupOrMeta)) return groupOrMeta.createState(define);
+    return createGroupState(define, void 0, groupOrMeta);
+  })[0];
+  const [fresh] = useRetrackAll([created]);
   return fresh;
-};
+}
 
-export { resnapshot, useCreateGroup, useCreateState };
+export { retrack, useGroup, useTrackedState };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opshot",
-  "version": "0.1.0",
-  "description": "Valtio state with snapshot reads, one mutate write path, and snapshot-diff ops",
+  "version": "0.2.1",
+  "description": "Plain-object state for React: mutate it directly, re-render only the components that read what changed, and track every change operation",
   "type": "module",
   "exports": {
     ".": {
@@ -68,5 +68,9 @@
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.64.0",
     "vitest": "^4.1.10"
+  },
+  "allowScripts": {
+    "esbuild@0.27.7": true,
+    "unrs-resolver@1.12.2": true
   }
 }