opshot 0.1.1 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Cavender
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/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 like [valtio](https://github.com/pmndrs/valtio), but not a footgun.)
 
 ## Install
 
@@ -15,109 +10,248 @@ 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
-import { useCreateState } from "opshot/react";
+const [user, setUser] = useState({ name: "Ada", age: 36 });
 
-const Counter = () => {
-	const counter = useCreateState({ count: 0 });
+setUser((prev) => ({ ...prev, age: 37 }));
+```
+
+**opshot** state is a live mutable object: you assign the field.
+
+```tsx
+const user = useMutableState({ name: "Ada", age: 36 });
+
+user.age = 37;
+```
+
+## Bounded re-renders
+
+React re-renders a component and its children when its state changes.
+
+```tsx
+interface User {
+	name: string;
+	age: number;
+}
+
+const Parent = () => {
+	const [user, setUser] = useState<User>({ name: "Ada", age: 36 });
+
+	const birthday = () => setUser((prev) => ({ ...prev, age: prev.age + 1 }));
+
+	// A click re-renders Parent and Child.
+	return (
+		<>
+			<button onClick={birthday}>+</button>
+			<Child user={user} />
+		</>
+	);
+};
+
+const Child = ({ user }: { user: User }) => <p>{user.age}</p>;
+```
+
+**opshot** re-renders only what read the change. Wrap a child in `scope` 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.
 
-	// Mutate the object directly: assignments, push, delete all work.
-	const increment = () => counter.op.mutate((proxy) => proxy.count++);
+```tsx
+const Parent = () => {
+	const user = useMutableState<User>({ name: "Ada", age: 36 });
+
+	const birthday = () => {
+		user.age++;
+	};
 
-	return <button onClick={increment}>{counter.count}</button>;
+	// A click re-renders only Child.
+	return (
+		<>
+			<button onClick={birthday}>+</button>
+			<Child user={user} />
+		</>
+	);
 };
+
+const Child = scope<{ user: User }>(({ user }) => <p>{user.age}</p>);
 ```
 
-## Creating state
+This is how you optimize re-rendering across your component tree: place `scope` boundaries where you want re-renders contained, and each boundary re-renders only when a field it read changes. `useMutableState` is a boundary itself.
+
+## Creating State
 
 ```tsx
-import { ref } from "opshot";
-import { useCreateState } from "opshot/react";
+import { ignore, unsafeTrack, useMutableState, type Ignored, type UnsafeTracked } from "opshot";
+
+interface PlayerState {
+	position: number;
+	element: Ignored<HTMLAudioElement>;
+	queue: UnsafeTracked<Playlist>;
+	seek: (position: number) => void;
+}
 
 const Player = () => {
-	const player = useCreateState((mutate, get) => ({
+	const player = useMutableState<PlayerState>({
 		position: 0,
 
-		// ref() keeps a value out of reactivity and ops.
-		element: ref(new Audio()),
+		// ignore() keeps a value out of reactivity and ops.
+		element: ignore(new Audio()),
 
-		// get() reads the current values.
-		seek: (position: number) => {
-			get().element.currentTime = position;
+		// unsafeTrack() tracks all the values it can, even if there is weird behaviour
+		queue: unsafeTrack(new Playlist()),
 
-			mutate((proxy) => (proxy.position = position));
+		seek(position: number) {
+			this.element.currentTime = position;
+
+			if (this.position === position) return;
+
+			this.position = position;
 		},
-	}));
+	});
 
 	// ...
 };
 ```
 
-## state.op
+## Constraints
+
+opshot tracks plain data.
 
-Everything opshot attaches lives under one reserved key, `op`.
+It can't track:
+
+- Internal slots (language level features like in Map)
+- #private fields (hidden at the language level)
+- Arrow methods on classes (they write to the original object, not the tracked one)
+- Array subclasses (the prototype is lost when copied)
+
+Use `ignore` or `unsafeTrack` when dealing with these.
+
+## Tracked collections
+
+`TrackedMap`, `TrackedSet`, and `TrackedDate` stand in for the built-ins opshot rejects. They have the exact same API as their counterparts.
 
 ```ts
-// The write path. An optional second argument is passed to every subscriber.
-counter.op.mutate((proxy) => {}, { transactionKey: "drag" });
+import { TrackedMap, useMutableState } from "opshot";
 
-// Hears every op this state emits; returns an unsubscribe.
-const unsubscribe = counter.op.subscribe((state, ops, options) => {
-	// ...
-});
+const state = useMutableState({ index: new TrackedMap<string, number>() });
+
+state.index.set("a", 1);
+```
+
+## Subscribe
 
-// State references are not reliable for equality: every mutation produces a new one. Use this instead.
-counter.op.isSameState(other);
+`subscribe` hears every change to a state.
 
-// True while a mutate callback is running.
-counter.op.isMutating;
+```tsx
+import { useEffect } from "react";
+import { subscribe, useMutableState } from "opshot";
 
-// The current values as your plain object, op stripped: for serializing and reads outside render.
-counter.op.unwrap();
+const Counter = () => {
+	const counter = useMutableState({ count: 0 });
 
-// The underlying valtio proxy, typed object: an escape hatch.
-counter.op.proxy;
+	useEffect(
+		() =>
+			subscribe(counter, (ops, meta) => {
+				// ops: [{
+				//   do:   { op: "replace", path: ["count"], value: 1 },
+				//   undo: { op: "replace", path: ["count"], value: 0 },
+				// }]
+				// meta: whatever the writer passed, or undefined for bare writes
+			}),
+		[counter],
+	);
+
+	// ...
+};
 ```
 
 ## Ops
 
+An op is an invertible pair of `Operation` halves. Every half uses one of three verbs:
+
 ```ts
-const unsubscribe = counter.op.subscribe((state, ops, options) => {
-	// state: the snapshot these ops produced
-	// ops: [{
-	//   do:   { op: "replace", path: "/count", value: 1 },
-	//   undo: { op: "replace", path: "/count", value: 0 },
-	// }]
-});
+type OperationPath = ReadonlyArray<string | number>;
+
+type Operation =
+	| { readonly op: "add"; readonly path: OperationPath; readonly value: unknown }
+	| { readonly op: "replace"; readonly path: OperationPath; readonly value: unknown }
+	| { readonly op: "remove"; readonly path: OperationPath };
+
+interface Op {
+	readonly do: Operation;
+	readonly undo: Operation;
+}
 ```
 
-An op is a pair of [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) patch operations, each half carrying its own value, so any JSON Patch tool applies and inverts them.
+`applyOps` puts them back on a state, so a history is a list of ops and an undo is their `undo` halves in reverse.
 
-A subscriber must not write to the state it subscribes to; writing to a different state is fine.
+```tsx
+import { useEffect, useRef } from "react";
+import { applyOps, subscribe, useMutableState, type Op } from "opshot";
+
+const replay = {};
 
-Ops cost nothing until someone listens: a state with no subscribers, on itself or its group, skips computing them entirely.
+const Counter = () => {
+	const counter = useMutableState({ count: 0 });
+	const history = useRef<Array<ReadonlyArray<Op>>>([]);
+
+	useEffect(
+		() =>
+			subscribe(counter, (ops, meta) => {
+				// Skip our own replays, so undo doesn't record itself.
+				if (meta === replay) return;
+
+				history.current.push(ops);
+			}),
+		[counter],
+	);
+
+	const undo = () => {
+		const ops = history.current.pop();
+
+		if (!ops) return;
+
+		applyOps(
+			counter,
+			[...ops].reverse().map((op) => op.undo),
+			replay,
+		);
+	};
+
+	return (
+		<>
+			<button onClick={() => counter.count++}>+</button>
+			<button onClick={undo}>Undo</button>
+		</>
+	);
+};
+```
+
+Replay is exact for anything opshot can see: plain data. State behind a constraint is the exception.
+
+If your state is JSON serializable, **then ops are too**.
 
 ## Groups
 
-A group creates states and hears every op from the states it created: one stream for history, sync, and persistence.
+A group creates states and hears every op from the states it created: one stream for history, sync, persistence, etc.
 
 ```tsx
 import { useEffect } from "react";
-import { useCreateGroup, useCreateState } from "opshot/react";
+import { subscribe, useGroup, useMutableState } from "opshot";
 
 const Editor = () => {
-	// A lifetime-stable group.
-	const group = useCreateGroup();
+	const group = useGroup();
 
-	// Created through the group, so its ops reach the group's subscribers.
-	const doc = useCreateState({ items: new Array<string>() }, group);
+	// Created through the group, so their ops reach the group's subscribers.
+	const doc = useMutableState({ items: new Array<string>() }, group);
+	const selection = useMutableState({ index: 0 }, group);
 
 	useEffect(
 		() =>
-			// Fires for doc and every other state the group created.
-			group.subscribe((state, ops, options) => {
+			// Fires for doc, selection, and every other state the group created.
+			// state is whichever one changed.
+			subscribe(group, (state, ops, meta) => {
 				// ...
 			}),
 		[group],
@@ -127,47 +261,48 @@ const Editor = () => {
 };
 ```
 
-## resnapshot
+## Channels
 
-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.
-
-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 channel binds `transact`, `subscribe`, and `applyOps` to a typed meta convention, so a listener can tell its own writes from everyone else's.
 
 ```tsx
-import type { State } from "opshot";
-import { useCreateState } from "opshot/react";
+import { useEffect } from "react";
+import { createChannel, useMutableState } from "opshot";
 
-interface Counter {
-	title: string;
-	count: number;
+interface DocumentMeta {
+	replay?: boolean;
+	source?: string;
 }
 
-// Every click re-renders App and its whole subtree.
-const App = () => {
-	const counter = useCreateState<Counter>({ title: "Hits", count: 0 });
+const docChannel = createChannel<DocumentMeta>({ source: "editor" }); // set defaults
 
-	return (
-		<>
-			<h1>{counter.title}</h1>
-			<CounterButton counter={counter} />
-		</>
-	);
-};
+const TitleBar = () => {
+	const doc = useMutableState({ title: "Untitled" });
 
-const CounterButton = ({ counter }: { counter: State<Counter> }) => (
-	<button onClick={() => counter.op.mutate((proxy) => proxy.count++)}>{counter.count}</button>
-);
-```
+	useEffect(
+		() =>
+			docChannel.subscribe(doc, (ops, context) => {
+				// A bare write, or a transact from another channel: meta is unknown.
+				if (!context.isTransaction) return;
 
-Wrapping `CounterButton` in `resnapshot` subscribes it, so its `count` read becomes its own. A click now re-renders `CounterButton` alone:
+				// Own-channel transaction: meta is typed, with defaults merged.
+				if (context.meta.replay) return;
 
-```tsx
-import { resnapshot } from "opshot/react";
+				// ...
+			}),
+		[doc],
+	);
+
+	const rename = () => {
+		docChannel.transact(doc, () => {
+			doc.title = "Draft";
+		});
+	};
 
-// 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.
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -1,47 +1,185 @@
-import { Snapshot } from 'valtio/vanilla';
-export { Snapshot, ref } from 'valtio/vanilla';
+import { ComponentType, FC } from 'react';
 
-type PatchOperation = {
+type OperationPath = ReadonlyArray<string | number>;
+
+interface AddOperation {
     readonly op: "add";
-    readonly path: string;
+    readonly path: OperationPath;
     readonly value: unknown;
-} | {
+}
+interface ReplaceOperation {
     readonly op: "replace";
-    readonly path: string;
+    readonly path: OperationPath;
     readonly value: unknown;
-} | {
+}
+interface RemoveOperation {
     readonly op: "remove";
-    readonly path: string;
-};
+    readonly path: OperationPath;
+}
+type Operation = AddOperation | ReplaceOperation | RemoveOperation;
 interface Op {
-    readonly do: PatchOperation;
-    readonly undo: PatchOperation;
-}
-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;
-    readonly isMutating: boolean;
-    readonly mutate: Mutate<T>;
-    readonly subscribe: (listener: StateListener<T>) => () => void;
-    readonly isSameState: (other: unknown) => boolean;
-    readonly unwrap: () => Snapshot<T>;
-}
-type State<T extends object> = Snapshot<T> & {
-    readonly op: OpshotHandle<T>;
-};
-type DefineCallback<T extends object> = (mutate: Mutate<T>, get: () => State<T>) => T;
-type Define<T extends object> = DefineCallback<T> | T;
-declare function createState<T extends object>(define: Define<T>): State<T>;
-declare function isState(value: unknown): value is State<object>;
+    readonly do: Operation;
+    readonly undo: Operation;
+}
+
+type StateListener = (ops: ReadonlyArray<Op>, meta: unknown) => void;
+type GroupListener = (state: object, ops: ReadonlyArray<Op>, meta: unknown) => void;
 
 interface Group {
-    createState<T extends object>(define: Define<T>): State<T>;
-    subscribe(listener: StateListener<object>): () => void;
+    createMutableState<T extends object>(properties: T): T;
 }
 declare function createGroup(): Group;
 
-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 };
+type Context<M> = {
+    readonly isTransaction: true;
+    readonly meta: M;
+} | {
+    readonly isTransaction: false;
+    readonly meta: unknown;
+};
+declare function subscribe(group: Group, listener: GroupListener): () => void;
+declare function subscribe(state: object, listener: StateListener): () => void;
+
+interface Channel<M extends object> {
+    transact(state: object, mutate: () => void, meta?: Partial<M>): void;
+    subscribe(group: Group, listener: (state: object, ops: ReadonlyArray<Op>, context: Context<M>) => void): () => void;
+    subscribe(state: object, listener: (ops: ReadonlyArray<Op>, context: Context<M>) => void): () => void;
+    applyOps(state: object, operations: ReadonlyArray<Operation>, meta?: Partial<M>): void;
+}
+declare function createChannel<M extends object>(defaults?: M): Channel<M>;
+
+declare function createMutableState<T extends object>(properties: T, group?: Group): T;
+
+declare function identify(value: object): object;
+declare function isSameIdentity(first: object, second: object): boolean;
+
+declare function isState(value: unknown): value is object;
+
+declare function applyOps(state: object, operations: ReadonlyArray<Operation>, meta?: unknown): void;
+
+declare function diffSnapshots(before: object, after: object): Array<Op>;
+
+declare const ignoredMarker: unique symbol;
+type Ignored<T extends object> = T & {
+    readonly [ignoredMarker]: true;
+};
+declare const ignore: <T extends object>(value: T) => Ignored<T>;
+
+declare const unsafeTrackedBrand: unique symbol;
+type UnsafeTracked<T extends object> = T & {
+    readonly [unsafeTrackedBrand]: true;
+};
+declare function unsafeTrack<T extends object>(value: T): UnsafeTracked<T>;
+
+type DateConstructorArgs = [] | [value: number | string] | [
+    year: number,
+    monthIndex: number,
+    date?: number,
+    hours?: number,
+    minutes?: number,
+    seconds?: number,
+    milliseconds?: number
+];
+declare class TrackedDate {
+    private epochMs;
+    constructor(...args: DateConstructorArgs);
+    private readDate;
+    private write;
+    toString(): string;
+    toDateString(): string;
+    toTimeString(): string;
+    toLocaleString(locales?: Intl.LocalesArgument, options?: Intl.DateTimeFormatOptions): string;
+    toLocaleDateString(locales?: Intl.LocalesArgument, options?: Intl.DateTimeFormatOptions): string;
+    toLocaleTimeString(locales?: Intl.LocalesArgument, options?: Intl.DateTimeFormatOptions): string;
+    valueOf(): number;
+    getTime(): number;
+    getFullYear(): number;
+    getYear(): number;
+    getUTCFullYear(): number;
+    getMonth(): number;
+    getUTCMonth(): number;
+    getDate(): number;
+    getUTCDate(): number;
+    getDay(): number;
+    getUTCDay(): number;
+    getHours(): number;
+    getUTCHours(): number;
+    getMinutes(): number;
+    getUTCMinutes(): number;
+    getSeconds(): number;
+    getUTCSeconds(): number;
+    getMilliseconds(): number;
+    getUTCMilliseconds(): number;
+    getTimezoneOffset(): number;
+    setYear(year: number): number;
+    setTime(...args: [time: number]): number;
+    setMilliseconds(...args: [milliseconds: number]): number;
+    setUTCMilliseconds(...args: [milliseconds: number]): number;
+    setSeconds(...args: [seconds: number, milliseconds?: number]): number;
+    setUTCSeconds(...args: [seconds: number, milliseconds?: number]): number;
+    setMinutes(...args: [minutes: number, seconds?: number, milliseconds?: number]): number;
+    setUTCMinutes(...args: [minutes: number, seconds?: number, milliseconds?: number]): number;
+    setHours(...args: [hours: number, minutes?: number, seconds?: number, milliseconds?: number]): number;
+    setUTCHours(...args: [hours: number, minutes?: number, seconds?: number, milliseconds?: number]): number;
+    setDate(...args: [dateValue: number]): number;
+    setUTCDate(...args: [dateValue: number]): number;
+    setMonth(...args: [month: number, dateValue?: number]): number;
+    setUTCMonth(...args: [month: number, dateValue?: number]): number;
+    setFullYear(...args: [year: number, month?: number, dateValue?: number]): number;
+    setUTCFullYear(...args: [year: number, month?: number, dateValue?: number]): number;
+    toUTCString(): string;
+    toGMTString(): string;
+    toISOString(): string;
+    [Symbol.toPrimitive](hint: "default" | "string" | "number"): string | number;
+    readonly [Symbol.toStringTag]: "TrackedDate";
+}
+
+declare class TrackedMap<K, V> {
+    private slots;
+    private index;
+    private count;
+    constructor(entries?: Iterable<readonly [K, V]>);
+    get size(): number;
+    has(key: K): boolean;
+    get(key: K): V | undefined;
+    set(key: K, value: V): this;
+    delete(key: K): boolean;
+    clear(): void;
+    entries(): IterableIterator<[K, V]>;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    forEach(callback: (value: V, key: K, map: TrackedMap<K, V>) => void): void;
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+    readonly [Symbol.toStringTag]: "TrackedMap";
+}
+
+declare class TrackedSet<T> {
+    private slots;
+    private index;
+    private count;
+    constructor(values?: Iterable<T>);
+    get size(): number;
+    has(value: T): boolean;
+    add(value: T): this;
+    delete(value: T): boolean;
+    clear(): void;
+    entries(): IterableIterator<[T, T]>;
+    keys(): IterableIterator<T>;
+    values(): IterableIterator<T>;
+    forEach(callback: (value: T, key: T, set: TrackedSet<T>) => void): void;
+    [Symbol.iterator](): IterableIterator<T>;
+    readonly [Symbol.toStringTag]: "TrackedSet";
+}
+
+declare function transact(state: object, mutate: () => void, meta?: unknown): void;
+
+interface ScopeOptions {
+    readonly maxDepth?: number;
+}
+declare function scope<P extends object>(Component: ComponentType<P>, options?: ScopeOptions): FC<P>;
+
+declare function useGroup(): Group;
+
+declare function useMutableState<T extends object>(properties: T, group?: Group): T;
+
+export { type AddOperation, type Channel, type Context, type Group, type GroupListener, type Ignored, type Op, type Operation, type OperationPath, type RemoveOperation, type ReplaceOperation, type ScopeOptions, type StateListener, TrackedDate, TrackedMap, TrackedSet, type UnsafeTracked, applyOps, createChannel, createGroup, createMutableState, diffSnapshots, identify, ignore, isSameIdentity, isState, scope, subscribe, transact, unsafeTrack, useGroup, useMutableState };