preact-sigma 2.0.0 → 2.1.0

package/README.md

@@ -4,6 +4,19 @@
 
 You define a reusable state type once, then create instances wherever they make sense: inside components, in shared modules, or in plain TypeScript code. Each instance exposes readonly public state, tracked derived reads, imperative actions, and optional setup and event APIs.
 
+## Getting Started
+
+To add `preact-sigma` to your project:
+
+```bash
+npm install preact-sigma
+```
+
+If you use AI coding agents, this repo also includes agent-oriented guidance:
+
+- [llms.txt](./llms.txt) provides a compact overview of the API and recommended patterns.
+- Companion skills are available via `npx skills add alloc/preact-sigma`.
+
 ## What It Is
 
 At its core, `preact-sigma` lets you describe a stateful model as a constructor:
@@ -151,5 +164,6 @@ In Preact, the same constructor can be used with `useSigma(() => new TodoList(),
 - Use `computed(...)` for argument-free derived state, and use queries for reactive reads that need parameters.
 - Put writes in actions. A draft boundary is any point where sigma cannot keep reusing the current draft. `emit()`, `await`, and any action call other than a same-instance sync nested action call are draft boundaries, so call `this.commit()` before those boundaries when pending writes should become public.
 - Use `snapshot(instance)` and `replaceState(instance, snapshot)` for committed-state replay. They work on top-level state keys and stay outside action semantics.
+- Use `ref(value)` when a value should stay by reference in sigma's `Draft` and `Immutable` types. It only changes typing and does not change Immer's runtime drafting or freezing behavior.
 - Use `immerable` on custom classes only when they should participate in Immer drafting. `setAutoFreeze(false)` disables sigma's runtime deep-freezing when you need published state to stay unfrozen.
 - Use `setup(...)` for owned side effects, and always return cleanup resources for anything the instance starts.

package/dist/index.d.mts

@@ -1,6 +1,11 @@
 import { ReadonlySignal, action, batch, computed, effect, untracked } from "@preact/signals";
 import { Patch, freeze, immerable } from "immer";
 
+//#region src/internal/symbols.d.ts
+declare const sigmaStateBrand: unique symbol;
+declare const sigmaEventsBrand: unique symbol;
+declare const sigmaRefBrand: unique symbol;
+//#endregion
 //#region src/immer.d.ts
 type PrimitiveType = number | string | boolean;
 /** Object types that should never be mapped */
@@ -18,6 +23,7 @@ type IfAvailable<T, Fallback = void> = true | false extends (T extends never ? t
  * Set
  */
 type WeakReferences = IfAvailable<WeakMap<any, any>> | IfAvailable<WeakSet<any>>;
+type HasSigmaRefBrand<T> = [T] extends [object] ? typeof sigmaRefBrand extends keyof T ? true : false : false;
 type WritableDraft<T> = T extends any[] ? number extends T["length"] ? Draft<T[number]>[] : WritableNonArrayDraft<T> : WritableNonArrayDraft<T>;
 type WritableNonArrayDraft<T> = { -readonly [K in keyof T]: T[K] extends infer V ? (V extends object ? Draft<V> : V) : never };
 /**
@@ -25,17 +31,13 @@ type WritableNonArrayDraft<T> = { -readonly [K in keyof T]: T[K] extends infer V
  *
  * Use this instead of `immer.Draft`
  */
-type Draft<T> = T extends PrimitiveType ? T : T extends AtomicObject ? T : T extends ReadonlyMap<infer K, infer V> ? Map<Draft<K>, Draft<V>> : T extends ReadonlySet<infer V> ? Set<Draft<V>> : T extends WeakReferences ? T : T extends object ? WritableDraft<T> : T;
+type Draft<T> = T extends PrimitiveType ? T : T extends AtomicObject ? T : HasSigmaRefBrand<T> extends true ? T : T extends ReadonlyMap<infer K, infer V> ? Map<Draft<K>, Draft<V>> : T extends ReadonlySet<infer V> ? Set<Draft<V>> : T extends WeakReferences ? T : T extends object ? WritableDraft<T> : T;
 /**
  * Convert a mutable type into a readonly type.
  *
  * Use this instead of `immer.Immutable`
  */
-type Immutable<T> = T extends PrimitiveType ? T : T extends AtomicObject ? T : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<Immutable<K>, Immutable<V>> : T extends ReadonlySet<infer V> ? ReadonlySet<Immutable<V>> : T extends WeakReferences ? T : T extends object ? { readonly [K in keyof T]: Immutable<T[K]> } : T;
-//#endregion
-//#region src/internal/symbols.d.ts
-declare const sigmaStateBrand: unique symbol;
-declare const sigmaEventsBrand: unique symbol;
+type Immutable<T> = T extends PrimitiveType ? T : T extends AtomicObject ? T : HasSigmaRefBrand<T> extends true ? T : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<Immutable<K>, Immutable<V>> : T extends ReadonlySet<infer V> ? ReadonlySet<Immutable<V>> : T extends WeakReferences ? T : T extends object ? { readonly [K in keyof T]: Immutable<T[K]> } : T;
 //#endregion
 //#region src/internal/types.d.ts
 type AnyFunction = (...args: any[]) => any;
@@ -45,6 +47,7 @@ type DefaultStateValue<TValue> = TValue | DefaultStateInitializer<TValue>;
 type Disposable = {
   [Symbol.dispose](): void;
 };
+/** A type brand added by `ref(...)`. */
 /** The event map shape used by sigma types. */
 type AnyEvents = Record<string, object | void>;
 /** The top-level state object shape used by sigma types. */
@@ -143,6 +146,13 @@ declare function replaceState<T extends AnySigmaState>(publicInstance: T, nextSt
 //#region src/framework.d.ts
 /** Checks whether a value is a sigma-state instance. */
 declare function isSigmaState(value: unknown): value is AnySigmaState;
+/**
+ * Returns `value` unchanged and marks its type so sigma's Draft and Immutable
+ * helpers keep it by reference instead of recursively immerizing it.
+ */
+declare function ref<T extends object>(value: T): T & {
+  [sigmaRefBrand]?: true;
+};
 /** Creates a standalone tracked query function with the same signature as `fn`. */
 declare function query<TArgs extends any[], TResult>(fn: (this: void, ...args: TArgs) => TResult): typeof fn;
 /**
@@ -226,4 +236,4 @@ declare function useSigma<T extends AnySigmaState>(create: () => T, setupArgs?:
 /** Attaches an event listener in a component and cleans it up when dependencies change. */
 declare function useListener<TTarget extends EventTarget | AnySigmaState, TEvent extends InferEventType<TTarget>>(target: TTarget | null, name: TEvent, listener: InferListener<TTarget, TEvent>): void;
 //#endregion
-export { type AnyDefaultState, type AnyEvents, type AnyResource, type AnySigmaState, type AnySigmaStateWithEvents, type AnyState, InferEventType, InferListener, type InferSetupArgs, type SigmaObserveChange, type SigmaObserveOptions, type SigmaState, SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };
+export { type AnyDefaultState, type AnyEvents, type AnyResource, type AnySigmaState, type AnySigmaStateWithEvents, type AnyState, InferEventType, InferListener, type InferSetupArgs, type SigmaObserveChange, type SigmaObserveOptions, type SigmaState, SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, ref, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };

package/dist/index.mjs

@@ -520,6 +520,13 @@ Object.defineProperty(Sigma.prototype, sigmaStateBrand, { value: true });
 function isSigmaState(value) {
 	return Boolean(value && typeof value === "object" && value[sigmaStateBrand]);
 }
+/**
+* Returns `value` unchanged and marks its type so sigma's Draft and Immutable
+* helpers keep it by reference instead of recursively immerizing it.
+*/
+function ref(value) {
+	return value;
+}
 /** Creates a standalone tracked query function with the same signature as `fn`. */
 function query(fn) {
 	return ((...args) => computed$1(() => fn(...args)).value);
@@ -626,4 +633,4 @@ function useListener(target, name, listener) {
 	}, [target, name]);
 }
 //#endregion
-export { SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };
+export { SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, ref, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };

package/llms.txt

@@ -7,6 +7,7 @@
 - `state property`: A top-level property from `TState`, such as `draft` in `{ draft: string }`.
 - `computed`: A tracked getter declared with `.computed({ ... })`.
 - `query`: A tracked method declared with `.queries({ ... })` or created with `query(fn)`.
+- `ref`: A helper that keeps a value by reference in sigma's `Draft` and `Immutable` types without changing runtime behavior.
 - `action`: A method declared with `.actions({ ... })` that reads and writes through one Immer draft for one synchronous call.
 - `draft boundary`: Any point where sigma cannot keep reusing the current draft.
 - `setup handler`: A function declared with `.setup(fn)` that returns an array of cleanup resources.
@@ -17,6 +18,7 @@
 
 - For state shape, inference, and instance shape, read `Start Here`, `Inference`, `SigmaType`, and `Public Instance Shape`.
 - For mutation semantics, read `Critical Rules`, `actions`, `immerable`, and `setAutoFreeze`.
+- For type-level by-reference values, read `ref`.
 - For side effects and events, read `setup`, `Events`, `listen`, `useListener`, and `useSigma`.
 - For committed-state utilities, read `observe`, `snapshot`, and `replaceState`.
 
@@ -60,6 +62,7 @@ import {
   isSigmaState,
   listen,
   query,
+  ref,
   replaceState,
   setAutoFreeze,
   snapshot,
@@ -325,6 +328,17 @@ Behavior:
 - custom class instances without a true `[immerable]` property stay outside that freeze path
 - plain objects, arrays, `Map`, and `Set` already participate in normal Immer drafting without extra markers
 
+## `ref(value)`
+
+`ref(value)` returns `value` unchanged and marks its type so sigma's `Draft` and `Immutable` helpers keep that value by reference.
+
+Behavior:
+
+- it has no runtime effect
+- it only changes sigma's local `Draft` and `Immutable` typing
+- it prevents type-level recursive immerization for that value
+- it does not change whether Immer drafts or freezes the value at runtime
+
 ## `query(fn)`
 
 `query(fn)` creates a standalone tracked query helper.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preact-sigma",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "keywords": [],
   "license": "MIT",
   "author": "Alec Larson",