@vielzeug/ripple 1.2.0

package/dist/tracking.js

@@ -0,0 +1,76 @@
+//#region src/tracking.ts
+var e = 0, t = () => ++e, n = () => e, r = () => ({
+	activeDirty: "a",
+	batchDepth: 0,
+	dirtyWithEffectSubsA: /* @__PURE__ */ new Set(),
+	dirtyWithEffectSubsB: /* @__PURE__ */ new Set(),
+	pendingSubscribers: /* @__PURE__ */ new Set()
+}), i = {
+	scheduling: r(),
+	scopeCleanups: null,
+	tracking: null
+}, a = null, o = () => a === null ? i : a.get(), s = () => o().scheduling, c = () => a !== null, l = () => o().tracking, u = (e, t) => {
+	if (a !== null) {
+		let n = a.get();
+		return a.run({
+			...n,
+			tracking: e
+		}, t);
+	}
+	let n = i;
+	i = {
+		...i,
+		tracking: e
+	};
+	try {
+		return t();
+	} finally {
+		i = n;
+	}
+}, d = (e, t) => {
+	if (a !== null) {
+		let n = a.get();
+		return a.run({
+			...n,
+			scopeCleanups: e
+		}, t);
+	}
+	let n = i;
+	i = {
+		...i,
+		scopeCleanups: e
+	};
+	try {
+		return t();
+	} finally {
+		i = n;
+	}
+}, f = () => o().scopeCleanups, p = (e) => {
+	let t = l();
+	t?.kind === "effect" ? t.cleanups.push(e) : f()?.push(e);
+}, m = (e) => {
+	let t = a;
+	return a = e, t;
+}, h = (e, t) => {
+	let n = l();
+	return n === null ? t() : u({
+		...n,
+		sourceObserver: e
+	}, t);
+}, g = (e) => u(null, e), _ = (e) => {
+	let t = l();
+	if (t !== null) {
+		if (t.sourceObserver?.(e), t.kind === "computed") t.depCollector.push({
+			source: e,
+			version: e.version
+		});
+		else if (t.kind === "effect") {
+			let n = t.effect;
+			e.addEffectSub(n), t.subscriptions.add(() => e.removeEffectSub(n)), t.deps.set(e, e.version);
+		}
+	}
+};
+//#endregion
+export { m as _installContextHook, p as autoRegisterDisposal, r as createSchedulingState, n as getRevision, s as getSchedulingState, f as getScopeCleanups, l as getTracking, c as hasContextHook, t as tickRevision, _ as trackSource, g as untrack, d as withScopeCleanups, h as withSourceObserver, u as withTracking };
+
+//# sourceMappingURL=tracking.js.map

package/dist/tracking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.js","names":[],"sources":["../src/tracking.ts"],"sourcesContent":["import type { ComputedBase, ReactiveBase } from './reactive-base';\nimport type { CleanupFn, Subscriber } from './types';\n\n// ── Global revision clock ─────────────────────────────────────────────────────\n//\n// Monotonically-increasing counter incremented on every signal write.\n// ComputedImpl records the clock value after each successful recompute and uses\n// it as an O(1) \"nothing has changed globally\" fast-path check in refreshIfDirty.\n\nlet globalRevision = 0;\n\nexport const tickRevision = (): number => ++globalRevision;\nexport const getRevision = (): number => globalRevision;\n\n// ── Internal types ────────────────────────────────────────────────────────────\n\nexport type DepEntry = {\n  source: ReactiveBase<unknown>;\n  version: number;\n};\n\n/** Called by trackSource to observe each reactive source accessed during a tracked run. */\nexport type SourceObserver = (source: ReactiveBase<unknown>) => void;\n\n// TrackingCtx carries both dep-collection state AND an optional sourceObserver.\n// Putting the observer inside the context (R12) scopes it to the specific effect/computed\n// run rather than making it a process-wide global — nested computed recomputes use their\n// own context (no observer), so the debugEffect pattern works without identity checks.\n// sourceObserver is shared across both branches and lives outside the discriminant union.\nexport type TrackingCtx = {\n  sourceObserver?: SourceObserver;\n} & (\n  | {\n      computed: ComputedBase<unknown>;\n      depCollector: DepEntry[];\n      kind: 'computed';\n    }\n  | {\n      cleanups: CleanupFn[];\n      deps: Map<ReactiveBase<unknown>, number>;\n      effect: Subscriber;\n      kind: 'effect';\n      subscriptions: Set<CleanupFn>;\n    }\n);\n\n// ── Scheduling state ────────────────────────────────────────────────────────\n//\n// Colocated here (rather than in scheduling.ts) so it can be a field of\n// ExecutionContext without a runtime circular import between tracking.ts and\n// scheduling.ts — scheduling.ts only needs `getSchedulingState()` and the\n// `SchedulingState` type (type-only import, erased at compile time).\n//\n// Isolating this per-request (via the SSR hook) closes the documented gap where\n// concurrent SSR requests share one flush queue: `batchDepth`, `pendingSubscribers`,\n// and the dirty-computed sets are the only scheduling fields that can observably\n// leak across requests (they persist across `await` boundaries via `batch()`\n// spanning shared module-level signals). The propagation epoch/stack in\n// scheduling.ts stay module-level scratch memory — they're only touched within a\n// single synchronous call stack, which JS's run-to-completion model already isolates.\n\nexport type SchedulingState = {\n  activeDirty: 'a' | 'b';\n  batchDepth: number;\n  readonly dirtyWithEffectSubsA: Set<ComputedBase<unknown>>;\n  readonly dirtyWithEffectSubsB: Set<ComputedBase<unknown>>;\n  readonly pendingSubscribers: Set<Subscriber>;\n};\n\nexport const createSchedulingState = (): SchedulingState => ({\n  activeDirty: 'a',\n  batchDepth: 0,\n  dirtyWithEffectSubsA: new Set(),\n  dirtyWithEffectSubsB: new Set(),\n  pendingSubscribers: new Set(),\n});\n\n// ── ExecutionContext ──────────────────────────────────────────────────────────\n//\n// Unified context replaces two separate globals (_tracking and _scopeStack).\n// Both the dep-tracking context and the innermost scope's cleanup array live here.\n// The SSR hook overrides the entire context per-request — fixing the prior bug\n// where scope cleanups were always a process-wide singleton even with the hook.\n\nexport type ExecutionContext = {\n  readonly scheduling: SchedulingState;\n  readonly scopeCleanups: CleanupFn[] | null;\n  readonly tracking: TrackingCtx | null;\n};\n\nexport type ContextHook = {\n  get(): ExecutionContext;\n  run<T>(ctx: ExecutionContext, fn: () => T): T;\n};\n\nlet _ctx: ExecutionContext = { scheduling: createSchedulingState(), scopeCleanups: null, tracking: null };\nlet _hook: ContextHook | null = null;\n\nconst getCtx = (): ExecutionContext => (_hook !== null ? _hook.get() : _ctx);\n\n/** Returns the scheduling-state bucket for the active execution context (module-level singleton outside SSR). */\nexport const getSchedulingState = (): SchedulingState => getCtx().scheduling;\n\n/** `true` once an SSR context hook is installed — scheduling state is then request-isolated. */\nexport const hasContextHook = (): boolean => _hook !== null;\n\n// ── Tracking ──────────────────────────────────────────────────────────────────\n\nexport const getTracking = (): TrackingCtx | null => getCtx().tracking;\n\nexport const withTracking = <T>(tracking: TrackingCtx | null, fn: () => T): T => {\n  if (_hook !== null) {\n    const current = _hook.get();\n\n    return _hook.run({ ...current, tracking }, fn);\n  }\n\n  const prev = _ctx;\n\n  _ctx = { ..._ctx, tracking };\n\n  try {\n    return fn();\n  } finally {\n    _ctx = prev;\n  }\n};\n\n// ── Scope cleanup ─────────────────────────────────────────────────────────────\n\n/**\n * Pushes `cleanups` as the active scope cleanup array for the duration of `fn`.\n * Any `onCleanup()` calls inside `fn` will register into these cleanups.\n * Effects and computed values created inside `fn` are also auto-registered.\n */\nexport const withScopeCleanups = <T>(cleanups: CleanupFn[], fn: () => T): T => {\n  if (_hook !== null) {\n    const current = _hook.get();\n\n    return _hook.run({ ...current, scopeCleanups: cleanups }, fn);\n  }\n\n  const prev = _ctx;\n\n  _ctx = { ..._ctx, scopeCleanups: cleanups };\n\n  try {\n    return fn();\n  } finally {\n    _ctx = prev;\n  }\n};\n\n/**\n * Returns the cleanup array of the innermost active scope, or `null` if not inside a scope.\n */\nexport const getScopeCleanups = (): CleanupFn[] | null => getCtx().scopeCleanups;\n\n// ── Auto-disposal ───────────────────────────────────────────────────────────────\n//\n// Shared by every primitive that ties its own lifetime to the context it was\n// created in (computed(), resource()): dispose when the enclosing effect re-runs\n// or disposes, or — if not inside an effect — when the enclosing scope disposes.\n// No-op if neither is active (the caller owns disposal directly).\n\n/**\n * Registers `dispose` to run when the enclosing effect re-runs/disposes, or —\n * if there is no enclosing effect — when the enclosing scope disposes.\n */\nexport const autoRegisterDisposal = (dispose: CleanupFn): void => {\n  const ctx = getTracking();\n\n  if (ctx?.kind === 'effect') {\n    ctx.cleanups.push(dispose);\n  } else {\n    getScopeCleanups()?.push(dispose);\n  }\n};\n\n// ── Context hook (for SSR) ────────────────────────────────────────────────────\n\n/**\n * @internal Used only by `/ripple/ssr`.\n * Installs a context hook that overrides both tracking and scope-cleanup access.\n * Returns the previous hook so callers can restore it.\n */\nexport const _installContextHook = (hook: ContextHook | null): ContextHook | null => {\n  const prev = _hook;\n\n  _hook = hook;\n\n  return prev;\n};\n\n// ── Source observer ───────────────────────────────────────────────────────────\n//\n// Observer is now scoped to the active TrackingCtx instead of a process-wide global.\n// This means it only fires for direct deps of the current effect/computed — nested\n// computed recomputes use their own context (no observer) so no identity check needed.\n\n/**\n * Runs `fn` while calling `observer` for every reactive source directly accessed.\n * Used by `debugEffect` to detect which sources changed between runs.\n * No-op if called outside an active tracking context.\n */\nexport const withSourceObserver = <T>(observer: SourceObserver, fn: () => T): T => {\n  const current = getTracking();\n\n  if (current === null) return fn();\n\n  return withTracking({ ...current, sourceObserver: observer }, fn);\n};\n\n// ── untrack ───────────────────────────────────────────────────────────────────\n\n/**\n * Runs `fn` without recording any reactive reads as dependencies of the enclosing\n * effect or computed. Useful when you need to read reactive state \"silently\".\n *\n * @example\n * ```ts\n * effect(() => {\n *   const a = count.value;               // tracked\n *   const b = untrack(() => name.value); // NOT tracked — no re-run when name changes\n * });\n * ```\n */\nexport const untrack = <T>(fn: () => T): T => withTracking(null, fn);\n\n// ── trackSource ───────────────────────────────────────────────────────────────\n//\n// Records `source` as a dependency of the currently active tracking context.\n// For computed contexts: only records the dep entry — addComputedSub is called\n// later by updateDeps() in computed.ts (only for genuinely NEW deps, preventing\n// duplicate WeakRef entries).\n// For effect contexts: immediately subscribes the effect to the source and\n// records the dep for getDependencies().\n\nexport const trackSource = (source: ReactiveBase<unknown>): void => {\n  const ctx = getTracking();\n\n  if (ctx === null) return;\n\n  ctx.sourceObserver?.(source);\n\n  if (ctx.kind === 'computed') {\n    ctx.depCollector.push({ source, version: source.version });\n  } else if (ctx.kind === 'effect') {\n    const owner = ctx.effect;\n\n    source.addEffectSub(owner);\n    ctx.subscriptions.add(() => source.removeEffectSub(owner));\n    ctx.deps.set(source, source.version);\n  }\n};\n"],"mappings":";AASA,IAAI,IAAiB,GAER,UAA6B,EAAE,GAC/B,UAA4B,GAyD5B,WAAgD;CAC3D,aAAa;CACb,YAAY;CACZ,sCAAsB,IAAI,IAAI;CAC9B,sCAAsB,IAAI,IAAI;CAC9B,oCAAoB,IAAI,IAAI;AAC9B,IAoBI,IAAyB;CAAE,YAAY,EAAsB;CAAG,eAAe;CAAM,UAAU;AAAK,GACpG,IAA4B,MAE1B,UAAkC,MAAU,OAAqB,IAAd,EAAM,IAAI,GAGtD,UAA4C,EAAO,CAAC,CAAC,YAGrD,UAAgC,MAAU,MAI1C,UAAwC,EAAO,CAAC,CAAC,UAEjD,KAAmB,GAA8B,MAAmB;CAC/E,IAAI,MAAU,MAAM;EAClB,IAAM,IAAU,EAAM,IAAI;EAE1B,OAAO,EAAM,IAAI;GAAE,GAAG;GAAS;EAAS,GAAG,CAAE;CAC/C;CAEA,IAAM,IAAO;CAEb,IAAO;EAAE,GAAG;EAAM;CAAS;CAE3B,IAAI;EACF,OAAO,EAAG;CACZ,UAAU;EACR,IAAO;CACT;AACF,GASa,KAAwB,GAAuB,MAAmB;CAC7E,IAAI,MAAU,MAAM;EAClB,IAAM,IAAU,EAAM,IAAI;EAE1B,OAAO,EAAM,IAAI;GAAE,GAAG;GAAS,eAAe;EAAS,GAAG,CAAE;CAC9D;CAEA,IAAM,IAAO;CAEb,IAAO;EAAE,GAAG;EAAM,eAAe;CAAS;CAE1C,IAAI;EACF,OAAO,EAAG;CACZ,UAAU;EACR,IAAO;CACT;AACF,GAKa,UAA6C,EAAO,CAAC,CAAC,eAatD,KAAwB,MAA6B;CAChE,IAAM,IAAM,EAAY;CAExB,AAAI,GAAK,SAAS,WAChB,EAAI,SAAS,KAAK,CAAO,IAEzB,EAAiB,CAAC,EAAE,KAAK,CAAO;AAEpC,GASa,KAAuB,MAAiD;CACnF,IAAM,IAAO;CAIb,OAFA,IAAQ,GAED;AACT,GAaa,KAAyB,GAA0B,MAAmB;CACjF,IAAM,IAAU,EAAY;CAI5B,OAFI,MAAY,OAAa,EAAG,IAEzB,EAAa;EAAE,GAAG;EAAS,gBAAgB;CAAS,GAAG,CAAE;AAClE,GAgBa,KAAc,MAAmB,EAAa,MAAM,CAAE,GAWtD,KAAe,MAAwC;CAClE,IAAM,IAAM,EAAY;CAEpB,UAAQ,MAIZ;MAFA,EAAI,iBAAiB,CAAM,GAEvB,EAAI,SAAS,YACf,EAAI,aAAa,KAAK;GAAE;GAAQ,SAAS,EAAO;EAAQ,CAAC;OACpD,IAAI,EAAI,SAAS,UAAU;GAChC,IAAM,IAAQ,EAAI;GAIlB,AAFA,EAAO,aAAa,CAAK,GACzB,EAAI,cAAc,UAAU,EAAO,gBAAgB,CAAK,CAAC,GACzD,EAAI,KAAK,IAAI,GAAQ,EAAO,OAAO;EACrC;;AACF"}

package/dist/types.d.ts

@@ -0,0 +1,315 @@
+export type CleanupFn = () => void;
+export type EffectCallback = () => CleanupFn | void;
+export type AsyncEffectCallback = (signal: AbortSignal, owner: Scope) => Promise<CleanupFn | void>;
+export type EqualityFn<T> = (a: T, b: T) => boolean;
+/**
+ * Controls when an effect re-runs after a dependency changes.
+ * - `'sync'` (default): runs immediately in the same flush.
+ * - `'microtask'`: deferred to the next microtask.
+ */
+export type EffectScheduler = 'microtask' | 'sync';
+/** Options accepted by `computed()`. */
+export type ComputedOptions<T> = {
+    equals?: EqualityFn<T>;
+    name?: string;
+};
+/** Options accepted by `signal()`. */
+export type SignalOptions<T> = {
+    equals?: EqualityFn<T>;
+    name?: string;
+};
+export type EffectOptions = {
+    name?: string;
+    scheduler?: EffectScheduler;
+};
+export type EffectAsyncOptions = {
+    /** Name used to identify this async effect in DevTools. */
+    name?: string;
+    onError?: (error: unknown) => void;
+};
+export interface Subscription {
+    dispose(): void;
+    /** `true` after `dispose()` has been called. */
+    readonly disposed: boolean;
+    [Symbol.dispose](): void;
+}
+/**
+ * A snapshot of one reactive dependency recorded by an effect.
+ * Returned by `EffectHandle.getDependencies()`.
+ */
+export type DepInfo = {
+    readonly kind: 'computed' | 'signal';
+    readonly name?: string;
+};
+/**
+ * Extended handle returned by `effect()`.
+ * Extends `Subscription` with `getDependencies()` for reactive graph introspection.
+ *
+ * @example
+ * ```ts
+ * const handle = effect(() => { console.log(count.value); });
+ * console.log(handle.getDependencies()); // [{ name: 'count' }]
+ * handle.dispose();
+ * ```
+ */
+export interface EffectHandle extends Subscription {
+    /**
+     * Returns the reactive sources the effect is currently subscribed to.
+     * Reflects the deps collected during the last completed run.
+     * Returns an empty array after `dispose()`.
+     */
+    getDependencies(): ReadonlyArray<DepInfo>;
+}
+/**
+ * Extended async subscription returned by `effectAsync()`.
+ * Adds `run()` for structured concurrency — await the current async run before proceeding.
+ */
+export interface AsyncSubscription extends Subscription {
+    /** Awaits the current async run without disposing the effect. Resolves immediately if idle. */
+    run(): Promise<void>;
+    /** ES2024 `await using` compatible async disposal. Stops the effect and awaits full teardown. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export type WatchOptions<T> = {
+    equals?: EqualityFn<T>;
+    immediate?: boolean;
+    name?: string;
+    /** Auto-dispose the watch after the first callback invocation. */
+    once?: boolean;
+};
+export type ResourceOptions<T> = {
+    /** Value exposed via `data` while the first run is loading. */
+    initialValue?: T;
+    /** Debug name for the internal effect and state signal. */
+    name?: string;
+};
+/**
+ * Discriminated-union state emitted by a `resource()` signal.
+ *
+ * - `'loading'` — async factory is in-flight. `data` carries the last fulfilled value (if any).
+ * - `'ready'`   — factory resolved. `data` is the fulfilled value.
+ * - `'error'`   — factory rejected. `error` holds the thrown value. `data` carries the last fulfilled value (if any).
+ *
+ * @example
+ * ```ts
+ * const user = resource(async () => fetchUser(id.value));
+ *
+ * effect(() => {
+ *   const s = user.value;
+ *   if (s.status === 'loading') return showSpinner();
+ *   if (s.status === 'error')   return showError(s.error);
+ *   renderUser(s.data);
+ * });
+ * ```
+ */
+export type ResourceState<T> = {
+    readonly data?: T;
+    readonly status: 'loading';
+} | {
+    readonly data: T;
+    readonly status: 'ready';
+} | {
+    readonly data?: T;
+    readonly error: unknown;
+    readonly status: 'error';
+};
+/**
+ * Disposable handle returned by `resource()`. Extends `Computed<ResourceState<T>>`
+ * with `refresh()` for manually forcing a re-fetch.
+ */
+export interface Resource<T> extends Computed<ResourceState<T>> {
+    /**
+     * Forces the factory to re-run immediately, aborting any in-flight run —
+     * even if no tracked dependency changed. No-op after `dispose()`.
+     */
+    refresh(): void;
+}
+/**
+ * A single snapshot entry in `StoreWithHistory`.
+ * Carries the frozen state and an optional label for annotated checkpoints.
+ */
+export type HistoryEntry<T> = {
+    readonly label?: string;
+    readonly state: Readonly<T>;
+};
+/**
+ * The minimal read-only contract for consuming any reactive value.
+ * Effects and computed functions read `.value` (tracked) or `peek()` (untracked).
+ * Use `subscribe()` for external imperative listeners.
+ */
+export interface Readable<T> {
+    /** `true` after the underlying node has been disposed. */
+    readonly disposed: boolean;
+    /** The debug name assigned at creation time, or `undefined` if unnamed. */
+    readonly name?: string;
+    peek(): T;
+    /**
+     * Subscribes a listener to value change notifications.
+     * Implementations MUST NOT invoke `listener` synchronously during registration.
+     */
+    subscribe(listener: () => void): Subscription;
+    readonly value: T;
+}
+/**
+ * A disposable derived value. The holder is responsible for calling `dispose()`.
+ * Returned by `computed()`, `readonly()`, and `resource()`.
+ */
+export interface Computed<T> extends Readable<T> {
+    dispose(): void;
+    [Symbol.dispose](): void;
+}
+/**
+ * A writable owned signal. The holder can both read and write `.value`,
+ * and is responsible for calling `dispose()` when done.
+ */
+export interface Signal<T> extends Computed<T> {
+    value: T;
+}
+/**
+ * Extracts the value type at a dot-separated path `P` within object type `T`.
+ *
+ * @example
+ * type City = PathValue<{ user: { address: { city: string } } }, 'user.address.city'>
+ * // → string
+ */
+export type PathValue<T, P extends string> = P extends keyof T ? T[P] : P extends `${infer K}.${infer Rest}` ? K extends keyof T ? PathValue<T[K], Rest> : never : never;
+/**
+ * A fine-grained reactive store for objects.
+ * Extends `Computed<Readonly<T>>` — `store.value` provides a tracked whole-store read.
+ *
+ * `lens()` is the primary reactive read/write API — it returns a `Signal` for
+ * a specific property or nested path and registers fine-grained dependencies.
+ * `peek()` returns a non-reactive snapshot (useful for serialization).
+ * `subscribe()` fires on any mutation (useful for adapters like `storeWithHistory`).
+ */
+export interface Store<T extends object> extends Computed<Readonly<T>> {
+    /**
+     * Returns a writable `Signal` scoped to a single property or nested path.
+     * Reads register a fine-grained dependency on that property's signal —
+     * unrelated patches do NOT re-run effects watching this lens.
+     * Lenses are cached — `store.lens('x') === store.lens('x')`.
+     */
+    lens<P extends string>(path: P): Signal<PathValue<T, P>>;
+    /** Atomic partial update — only changed keys notify their subscribers. */
+    patch(partial: Partial<T>): void;
+    /**
+     * Returns a non-reactive snapshot of the current state.
+     * Use for serialization or one-off reads outside reactive contexts.
+     */
+    peek(): Readonly<T>;
+    /**
+     * Replaces the entire store state by passing the current state to `fn` and
+     * applying the returned value. Only changed properties trigger downstream effects.
+     */
+    replace(fn: (state: Readonly<T>) => T): void;
+    /** Resets the store to its initial state. */
+    reset(): void;
+    /**
+     * Subscribes to any store mutation (patch / replace / reset / lens write).
+     * Used by external adapters — prefer `store.lens()` for reactive reads.
+     */
+    subscribe(listener: () => void): Subscription;
+}
+/**
+ * A lifecycle scope that collects cleanup functions and runs them on dispose.
+ * Effects and computeds created inside `scope.run()` auto-register their disposal.
+ */
+export interface Scope {
+    /**
+     * Registers `fn` to run when this scope is disposed.
+     * Throws `RippleDisposedScopeError` if called on an already-disposed scope.
+     * Use this from within an effect body to explicitly direct a cleanup into the scope
+     * rather than the effect's own cleanup queue.
+     */
+    add(fn: CleanupFn): void;
+    /** `AbortSignal` that is aborted when `dispose()` is called. Use to tie external lifetimes to this scope. */
+    readonly disposalSignal: AbortSignal;
+    dispose(): void;
+    /** `true` after `dispose()` has been called. */
+    readonly disposed: boolean;
+    /**
+     * Runs `fn` inside this scope's cleanup context.
+     * `onCleanup()` calls and resource auto-disposals inside `fn` are registered
+     * to this scope when there is no enclosing effect or computed context.
+     * Reactive reads inside `fn` are tracked normally against any enclosing effect.
+     * Throws `RippleDisposedScopeError` if the scope has already been disposed.
+     */
+    run<T>(fn: () => T): T;
+    [Symbol.dispose](): void;
+}
+/**
+ * An undo/redo adapter wrapping a `Store<T>`.
+ * Extends `Store<T>` directly — all store mutations (`patch`, `replace`, `reset`, `lens`)
+ * work on the history adapter without `.store` indirection.
+ *
+ * History is **explicit** — call `push()` or `pushNamed()` after any mutation you want undoable.
+ *
+ * @example
+ * ```ts
+ * const h = storeWithHistory({ count: 0 });
+ *
+ * h.patch({ count: 1 });
+ * h.push();           // save a checkpoint
+ * h.undo();           // restore to { count: 0 }
+ * h.redo();           // restore to { count: 1 }
+ * ```
+ */
+export interface StoreWithHistory<T extends object> extends Store<T> {
+    /** `true` when there is at least one snapshot ahead to redo. Reactive — reads inside effects re-run on change. */
+    readonly canRedo: boolean;
+    /** `true` when there is at least one snapshot to undo to. Reactive — reads inside effects re-run on change. */
+    readonly canUndo: boolean;
+    /** Returns the history entry at the given index (0 = oldest). */
+    historyAt(index: number): HistoryEntry<T> | undefined;
+    /** Number of snapshots currently in history. */
+    readonly historyLength: number;
+    /** Saves the current store state as an explicit undo checkpoint. */
+    push(): void;
+    /**
+     * Saves the current store state as an annotated checkpoint.
+     * Use to mark significant transitions (e.g. `'import'`, `'reset'`) so time-travel
+     * debuggers can distinguish user-initiated from programmatic mutations.
+     */
+    pushNamed(label: string): void;
+    /** Move forward one snapshot. No-op when at the most recent checkpoint. */
+    redo(): void;
+    /** The underlying store — kept as an escape hatch for adapters that need direct store access. */
+    readonly store: Store<T>;
+    /** Move back one snapshot. No-op when at the oldest checkpoint. */
+    undo(): void;
+}
+export type Subscriber = () => void;
+/** Event emitted when a signal's value changes. */
+export type WriteEvent = {
+    name: string | undefined;
+    newValue: unknown;
+    oldValue: unknown;
+};
+/** Event emitted when a computed recomputes, or when an effect runs. */
+export type NamedEvent = {
+    name: string | undefined;
+};
+/** Event emitted when a signal, computed, effect, or store is disposed. */
+export type DisposeEvent = {
+    kind: 'computed' | 'effect' | 'signal' | 'store';
+    name: string | undefined;
+};
+/** Event emitted when a store-level mutation occurs. `path` is populated for `kind: 'lens'`. */
+export type MutateEvent = {
+    kind: 'patch' | 'replace' | 'reset' | 'lens';
+    name: string | undefined;
+    path?: string;
+};
+export type RippleDevToolsHook = {
+    /** Called when a computed signal recomputes. */
+    compute?(event: NamedEvent): void;
+    /** Called when a signal, computed, or effect is disposed. */
+    dispose?(event: DisposeEvent): void;
+    /** Called when a store-level mutation (patch/replace/reset/lens) occurs. */
+    mutate?(event: MutateEvent): void;
+    /** Called when an effect starts running. */
+    run?(event: NamedEvent): void;
+    /** Called when a signal's value changes. */
+    write?(event: WriteEvent): void;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC;AACnC,MAAM,MAAM,cAAc,GAAG,MAAM,SAAS,GAAG,IAAI,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;AACnG,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;AAEpD;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,MAAM,CAAC;AAEnD,wCAAwC;AACxC,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;IAC/B,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,sCAAsC;AACtC,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;IAC7B,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC,CAAC;AAIF,MAAM,WAAW,YAAY;IAC3B,OAAO,IAAI,IAAI,CAAC;IAChB,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD;;;;OAIG;IACH,eAAe,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,+FAA+F;IAC/F,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACrB,iGAAiG;IACjG,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAID,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAC5B,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC;AAIF,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;IAC/B,+DAA+D;IAC/D,YAAY,CAAC,EAAE,CAAC,CAAC;IACjB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IACvB;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAE7E;;;GAGG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,CAAE,SAAQ,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAC7D;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAID;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;CAC7B,CAAC;AAIF;;;;GAIG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,IAAI,CAAC,CAAC;IACV;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,YAAY,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC;IAC9C,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,MAAM,CAAC,CAAC,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC;IAC5C,KAAK,EAAE,CAAC,CAAC;CACV;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,CAAC,GAC1D,CAAC,CAAC,CAAC,CAAC,GACJ,CAAC,SAAS,GAAG,MAAM,CAAC,IAAI,MAAM,IAAI,EAAE,GAClC,CAAC,SAAS,MAAM,CAAC,GACf,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GACrB,KAAK,GACP,KAAK,CAAC;AAEZ;;;;;;;;GAQG;AACH,MAAM,WAAW,KAAK,CAAC,CAAC,SAAS,MAAM,CAAE,SAAQ,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACpE;;;;;OAKG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACzD,0EAA0E;IAC1E,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,IAAI,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAC7C,6CAA6C;IAC7C,KAAK,IAAI,IAAI,CAAC;IACd;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,YAAY,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB,6GAA6G;IAC7G,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC;IACrC,OAAO,IAAI,IAAI,CAAC;IAChB,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAE,SAAQ,KAAK,CAAC,CAAC,CAAC;IAClE,kHAAkH;IAClH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+GAA+G;IAC/G,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,iEAAiE;IACjE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IACtD,gDAAgD;IAChD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,oEAAoE;IACpE,IAAI,IAAI,IAAI,CAAC;IACb;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,2EAA2E;IAC3E,IAAI,IAAI,IAAI,CAAC;IACb,iGAAiG;IACjG,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,mEAAmE;IACnE,IAAI,IAAI,IAAI,CAAC;CACd;AAID,MAAM,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC;AAQpC,mDAAmD;AACnD,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC;AAE5F,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtD,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE1G,gGAAgG;AAChG,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;IAC7C,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,gDAAgD;IAChD,OAAO,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAClC,6DAA6D;IAC7D,OAAO,CAAC,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC,4EAA4E;IAC5E,MAAM,CAAC,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC,4CAA4C;IAC5C,GAAG,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,4CAA4C;IAC5C,KAAK,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CACjC,CAAC"}

package/dist/utilities.cjs

@@ -0,0 +1,2 @@
+const e=require("./tracking.cjs"),t=require("./symbols.cjs");var n=e=>({get disposed(){return e.disposed},[t.IS_SIGNAL]:!0,get name(){return e.name},peek(){return e.peek()},subscribe(t){return e.subscribe(t)},get value(){return e.value}}),r=e=>typeof e==`object`&&!!e&&!!e[t.IS_SIGNAL],i=e=>r(e)&&!e[t.IS_COMPUTED]&&!e[t.IS_STORE],a=e=>typeof e==`object`&&!!e&&!!e[t.IS_COMPUTED],o=e=>typeof e==`object`&&!!e&&!!e[t.IS_STORE];exports.isComputed=a,exports.isReactive=r,exports.isSignal=i,exports.isStore=o,exports.readonly=n,exports.untrack=e.untrack;
+//# sourceMappingURL=utilities.cjs.map

package/dist/utilities.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.cjs","names":[],"sources":["../src/utilities.ts"],"sourcesContent":["import type { Computed, Readable, Signal } from './types';\n\nimport { IS_COMPUTED, IS_SIGNAL, IS_STORE } from './symbols';\nimport { untrack } from './tracking';\n\nexport { untrack };\n\n// ── Readonly wrapper ──────────────────────────────────────────────────────────\n//\n// readonly() returns Readable<T> — no dispose() because the wrapper does not\n// own the source. Callers retain ownership and must dispose the source themselves.\n// The [IS_SIGNAL] brand is set so isReactive(readonly(s)) and isSignal(readonly(s))\n// both return true (it is reactive, not IS_COMPUTED, not IS_STORE).\n// [IS_COMPUTED] is intentionally NOT set — the wrapper is not a Computed<T>\n// and does not have dispose().\n\n/**\n * Wraps a reactive value to produce a structurally read-only view.\n * The `value` setter is hidden. Delegates reads directly to the source —\n * no extra reactive graph node, no extra subscription.\n *\n * The caller retains ownership of the source and is responsible for disposing it.\n *\n * @example\n * ```ts\n * const count = signal(0);\n * const readCount = readonly(count);\n * readCount.value; // fine — tracks dep on count\n * // readCount.value = 1; // TypeScript error — Readable has no setter\n * ```\n */\nexport const readonly = <T>(source: Readable<T>): Readable<T> => {\n  const wrapper = {\n    get disposed(): boolean {\n      return source.disposed;\n    },\n    [IS_SIGNAL]: true as const,\n    get name(): string | undefined {\n      return source.name;\n    },\n    peek(): T {\n      return source.peek();\n    },\n    subscribe(listener: () => void) {\n      return source.subscribe(listener);\n    },\n    get value(): T {\n      return source.value;\n    },\n  };\n\n  return wrapper as unknown as Readable<T>;\n};\n\n// ── Type guards ───────────────────────────────────────────────────────────────\n\n/**\n * Returns `true` for any reactive value that implements `Readable<T>` — including\n * `signal()`, `computed()`, `store()`, and `readonly()` wrappers.\n *\n * This is the broad \"is this value reactive?\" check. Use `isSignal` for writable-only\n * signals, or `isComputed` to narrow to computed values.\n *\n * @example\n * ```ts\n * isReactive(signal(0))            // true\n * isReactive(computed(() => 1))    // true\n * isReactive(store({ x: 0 }))     // true\n * isReactive(readonly(signal(0)))  // true\n * isReactive({})                   // false\n * ```\n */\nexport const isReactive = <T = unknown>(value: unknown): value is Readable<T> =>\n  typeof value === 'object' && value !== null && !!(value as Record<typeof IS_SIGNAL, unknown>)[IS_SIGNAL];\n\n/**\n * Returns `true` only for writable `Signal<T>` values — excludes `computed()`, `store()`,\n * and `readonly()` wrappers.\n *\n * Use `isReactive` for the broad \"is this reactive?\" check.\n *\n * @example\n * ```ts\n * isSignal(signal(0))            // true\n * isSignal(computed(() => 1))    // false — computed excluded\n * isSignal(store({ x: 0 }))     // false — store excluded\n * isSignal(readonly(signal(0)))  // true — readonly has IS_SIGNAL, not IS_COMPUTED/IS_STORE\n * isSignal({})                   // false\n * ```\n */\nexport const isSignal = <T = unknown>(value: unknown): value is Signal<T> =>\n  isReactive(value) &&\n  !(value as unknown as Record<typeof IS_COMPUTED, unknown>)[IS_COMPUTED] &&\n  !(value as unknown as Record<typeof IS_STORE, unknown>)[IS_STORE];\n\nexport const isComputed = <T = unknown>(value: unknown): value is Computed<T> =>\n  typeof value === 'object' && value !== null && !!(value as Record<typeof IS_COMPUTED, unknown>)[IS_COMPUTED];\n\nexport const isStore = <T extends object = object>(value: unknown): value is import('./types').Store<T> =>\n  typeof value === 'object' && value !== null && !!(value as Record<typeof IS_STORE, unknown>)[IS_STORE];\n"],"mappings":"6DA+BA,IAAa,EAAe,IAoBnB,CAlBL,IAAI,UAAoB,CACtB,OAAO,EAAO,QAChB,GACC,EAAA,WAAY,GACb,IAAI,MAA2B,CAC7B,OAAO,EAAO,IAChB,EACA,MAAU,CACR,OAAO,EAAO,KAAK,CACrB,EACA,UAAU,EAAsB,CAC9B,OAAO,EAAO,UAAU,CAAQ,CAClC,EACA,IAAI,OAAW,CACb,OAAO,EAAO,KAChB,CAGK,GAqBI,EAA2B,GACtC,OAAO,GAAU,YAAY,GAAkB,CAAC,CAAE,EAA4C,EAAA,WAiBnF,EAAyB,GACpC,EAAW,CAAK,GAChB,CAAE,EAAyD,EAAA,cAC3D,CAAE,EAAsD,EAAA,UAE7C,EAA2B,GACtC,OAAO,GAAU,YAAY,GAAkB,CAAC,CAAE,EAA8C,EAAA,aAErF,EAAsC,GACjD,OAAO,GAAU,YAAY,GAAkB,CAAC,CAAE,EAA2C,EAAA"}

package/dist/utilities.d.ts

@@ -0,0 +1,55 @@
+import type { Computed, Readable, Signal } from './types';
+import { untrack } from './tracking';
+export { untrack };
+/**
+ * Wraps a reactive value to produce a structurally read-only view.
+ * The `value` setter is hidden. Delegates reads directly to the source —
+ * no extra reactive graph node, no extra subscription.
+ *
+ * The caller retains ownership of the source and is responsible for disposing it.
+ *
+ * @example
+ * ```ts
+ * const count = signal(0);
+ * const readCount = readonly(count);
+ * readCount.value; // fine — tracks dep on count
+ * // readCount.value = 1; // TypeScript error — Readable has no setter
+ * ```
+ */
+export declare const readonly: <T>(source: Readable<T>) => Readable<T>;
+/**
+ * Returns `true` for any reactive value that implements `Readable<T>` — including
+ * `signal()`, `computed()`, `store()`, and `readonly()` wrappers.
+ *
+ * This is the broad "is this value reactive?" check. Use `isSignal` for writable-only
+ * signals, or `isComputed` to narrow to computed values.
+ *
+ * @example
+ * ```ts
+ * isReactive(signal(0))            // true
+ * isReactive(computed(() => 1))    // true
+ * isReactive(store({ x: 0 }))     // true
+ * isReactive(readonly(signal(0)))  // true
+ * isReactive({})                   // false
+ * ```
+ */
+export declare const isReactive: <T = unknown>(value: unknown) => value is Readable<T>;
+/**
+ * Returns `true` only for writable `Signal<T>` values — excludes `computed()`, `store()`,
+ * and `readonly()` wrappers.
+ *
+ * Use `isReactive` for the broad "is this reactive?" check.
+ *
+ * @example
+ * ```ts
+ * isSignal(signal(0))            // true
+ * isSignal(computed(() => 1))    // false — computed excluded
+ * isSignal(store({ x: 0 }))     // false — store excluded
+ * isSignal(readonly(signal(0)))  // true — readonly has IS_SIGNAL, not IS_COMPUTED/IS_STORE
+ * isSignal({})                   // false
+ * ```
+ */
+export declare const isSignal: <T = unknown>(value: unknown) => value is Signal<T>;
+export declare const isComputed: <T = unknown>(value: unknown) => value is Computed<T>;
+export declare const isStore: <T extends object = object>(value: unknown) => value is import("./types").Store<T>;
+//# sourceMappingURL=utilities.d.ts.map

package/dist/utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAG1D,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC,OAAO,EAAE,OAAO,EAAE,CAAC;AAWnB;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,QAAQ,QAAQ,CAAC,CAAC,CAAC,KAAG,QAAQ,CAAC,CAAC,CAqB3D,CAAC;AAIF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,GAAG,OAAO,EAAE,OAAO,OAAO,KAAG,KAAK,IAAI,QAAQ,CAAC,CAAC,CAC8B,CAAC;AAE3G;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,GAAG,OAAO,EAAE,OAAO,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,CAAC,CAGL,CAAC;AAEpE,eAAO,MAAM,UAAU,GAAI,CAAC,GAAG,OAAO,EAAE,OAAO,OAAO,KAAG,KAAK,IAAI,QAAQ,CAAC,CAAC,CACkC,CAAC;AAE/G,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,OAAO,OAAO,KAAG,KAAK,IAAI,OAAO,SAAS,EAAE,KAAK,CAAC,CAAC,CACE,CAAC"}

package/dist/utilities.js

@@ -0,0 +1,25 @@
+import { untrack as e } from "./tracking.js";
+import { IS_COMPUTED as t, IS_SIGNAL as n, IS_STORE as r } from "./symbols.js";
+//#region src/utilities.ts
+var i = (e) => ({
+	get disposed() {
+		return e.disposed;
+	},
+	[n]: !0,
+	get name() {
+		return e.name;
+	},
+	peek() {
+		return e.peek();
+	},
+	subscribe(t) {
+		return e.subscribe(t);
+	},
+	get value() {
+		return e.value;
+	}
+}), a = (e) => typeof e == "object" && !!e && !!e[n], o = (e) => a(e) && !e[t] && !e[r], s = (e) => typeof e == "object" && !!e && !!e[t], c = (e) => typeof e == "object" && !!e && !!e[r];
+//#endregion
+export { s as isComputed, a as isReactive, o as isSignal, c as isStore, i as readonly, e as untrack };
+
+//# sourceMappingURL=utilities.js.map

package/dist/utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.js","names":[],"sources":["../src/utilities.ts"],"sourcesContent":["import type { Computed, Readable, Signal } from './types';\n\nimport { IS_COMPUTED, IS_SIGNAL, IS_STORE } from './symbols';\nimport { untrack } from './tracking';\n\nexport { untrack };\n\n// ── Readonly wrapper ──────────────────────────────────────────────────────────\n//\n// readonly() returns Readable<T> — no dispose() because the wrapper does not\n// own the source. Callers retain ownership and must dispose the source themselves.\n// The [IS_SIGNAL] brand is set so isReactive(readonly(s)) and isSignal(readonly(s))\n// both return true (it is reactive, not IS_COMPUTED, not IS_STORE).\n// [IS_COMPUTED] is intentionally NOT set — the wrapper is not a Computed<T>\n// and does not have dispose().\n\n/**\n * Wraps a reactive value to produce a structurally read-only view.\n * The `value` setter is hidden. Delegates reads directly to the source —\n * no extra reactive graph node, no extra subscription.\n *\n * The caller retains ownership of the source and is responsible for disposing it.\n *\n * @example\n * ```ts\n * const count = signal(0);\n * const readCount = readonly(count);\n * readCount.value; // fine — tracks dep on count\n * // readCount.value = 1; // TypeScript error — Readable has no setter\n * ```\n */\nexport const readonly = <T>(source: Readable<T>): Readable<T> => {\n  const wrapper = {\n    get disposed(): boolean {\n      return source.disposed;\n    },\n    [IS_SIGNAL]: true as const,\n    get name(): string | undefined {\n      return source.name;\n    },\n    peek(): T {\n      return source.peek();\n    },\n    subscribe(listener: () => void) {\n      return source.subscribe(listener);\n    },\n    get value(): T {\n      return source.value;\n    },\n  };\n\n  return wrapper as unknown as Readable<T>;\n};\n\n// ── Type guards ───────────────────────────────────────────────────────────────\n\n/**\n * Returns `true` for any reactive value that implements `Readable<T>` — including\n * `signal()`, `computed()`, `store()`, and `readonly()` wrappers.\n *\n * This is the broad \"is this value reactive?\" check. Use `isSignal` for writable-only\n * signals, or `isComputed` to narrow to computed values.\n *\n * @example\n * ```ts\n * isReactive(signal(0))            // true\n * isReactive(computed(() => 1))    // true\n * isReactive(store({ x: 0 }))     // true\n * isReactive(readonly(signal(0)))  // true\n * isReactive({})                   // false\n * ```\n */\nexport const isReactive = <T = unknown>(value: unknown): value is Readable<T> =>\n  typeof value === 'object' && value !== null && !!(value as Record<typeof IS_SIGNAL, unknown>)[IS_SIGNAL];\n\n/**\n * Returns `true` only for writable `Signal<T>` values — excludes `computed()`, `store()`,\n * and `readonly()` wrappers.\n *\n * Use `isReactive` for the broad \"is this reactive?\" check.\n *\n * @example\n * ```ts\n * isSignal(signal(0))            // true\n * isSignal(computed(() => 1))    // false — computed excluded\n * isSignal(store({ x: 0 }))     // false — store excluded\n * isSignal(readonly(signal(0)))  // true — readonly has IS_SIGNAL, not IS_COMPUTED/IS_STORE\n * isSignal({})                   // false\n * ```\n */\nexport const isSignal = <T = unknown>(value: unknown): value is Signal<T> =>\n  isReactive(value) &&\n  !(value as unknown as Record<typeof IS_COMPUTED, unknown>)[IS_COMPUTED] &&\n  !(value as unknown as Record<typeof IS_STORE, unknown>)[IS_STORE];\n\nexport const isComputed = <T = unknown>(value: unknown): value is Computed<T> =>\n  typeof value === 'object' && value !== null && !!(value as Record<typeof IS_COMPUTED, unknown>)[IS_COMPUTED];\n\nexport const isStore = <T extends object = object>(value: unknown): value is import('./types').Store<T> =>\n  typeof value === 'object' && value !== null && !!(value as Record<typeof IS_STORE, unknown>)[IS_STORE];\n"],"mappings":";;;AA+BA,IAAa,KAAe,OAoBnB;CAlBL,IAAI,WAAoB;EACtB,OAAO,EAAO;CAChB;EACC,IAAY;CACb,IAAI,OAA2B;EAC7B,OAAO,EAAO;CAChB;CACA,OAAU;EACR,OAAO,EAAO,KAAK;CACrB;CACA,UAAU,GAAsB;EAC9B,OAAO,EAAO,UAAU,CAAQ;CAClC;CACA,IAAI,QAAW;EACb,OAAO,EAAO;CAChB;AAGK,IAqBI,KAA2B,MACtC,OAAO,KAAU,cAAY,KAAkB,CAAC,CAAE,EAA4C,IAiBnF,KAAyB,MACpC,EAAW,CAAK,KAChB,CAAE,EAAyD,MAC3D,CAAE,EAAsD,IAE7C,KAA2B,MACtC,OAAO,KAAU,cAAY,KAAkB,CAAC,CAAE,EAA8C,IAErF,KAAsC,MACjD,OAAO,KAAU,cAAY,KAAkB,CAAC,CAAE,EAA2C"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@vielzeug/ripple",
+  "version": "1.2.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "description": "Fine-grained reactive state — signals, computed values, effects, stores, and reactive scopes",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./devtools": {
+      "source": "./src/devtools.ts",
+      "types": "./dist/devtools.d.ts",
+      "import": "./dist/devtools.js",
+      "require": "./dist/devtools.cjs"
+    },
+    "./ssr": {
+      "source": "./src/ssr/index.ts",
+      "types": "./dist/ssr/index.d.ts",
+      "import": "./dist/ssr/index.js",
+      "require": "./dist/ssr/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "vite build && pnpm run build:bundle && pnpm run build:types",
+    "build:types": "tsc -p tsconfig.declarations.json",
+    "fix": "eslint --fix src",
+    "lint": "eslint src",
+    "prepublishOnly": "pnpm run build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "build:bundle": "vite build --config vite.bundle.config.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "~6.0.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
+  }
+}