react-fine-grained-signals 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 akazawa
+
+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.ja.md

@@ -0,0 +1,53 @@
+# react-fine-grained-signals
+
+[English](README.md) | [日本語](README.ja.md)
+
+[alien-signals](https://www.npmjs.com/package/alien-signals) を基盤とした、React 19向けの実験的なfine-grainedレンダリングレイヤーです。小さなリアクティブプリミティブ、Reactフック、そして対象を意図的に絞ったDOMプロパティへの直接バインディング用JSXランタイムを提供します。このJSXランタイムは明示的に有効化した場合のみ使用されます。
+
+**React 19以降が必要です。** JSXランタイムは、React 18では利用できないcallback refのクリーンアップを使用します。
+
+## ドキュメント
+
+ライブラリの使い方のガイド、設計検討メモ、ドキュメント索引全体については[`docs/README.ja.md`](docs/README.ja.md)を参照してください。
+
+## インストール
+
+```sh
+# 公開予定のパッケージ名です。まだnpmには公開していません。
+pnpm add react-fine-grained-signals alien-signals
+```
+
+`alien-signals` はpeer dependencyなので、上のように併せてinstallしてください。
+
+`useSignals()` を自動挿入するオプションのbuild pluginは別途installします。[描画最適化](docs/rendering-optimization.ja.md)を参照してください。
+
+## 開発
+
+```sh
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+workspace aliasを使わないクリーンなVite consumerから、pack済みESM packageを検証するには次を実行します。
+
+```sh
+pnpm test:consumer
+```
+
+ブラウザ向けの概念実証では、サーバーでアプリをレンダーし、React 19でハイドレーションを行い、Chromium上でsignalの直接バインディングを検証します。
+
+```sh
+pnpm exec playwright install --only-shell chromium
+pnpm prepare:e2e
+pnpm test:browser
+```
+
+同じサンプルを `http://127.0.0.1:4173` で確認するには、`pnpm dev:browser` を実行してください。このコマンドは最初に変換パッケージをビルドします。
+
+## 謝辞
+
+- [alien-signals](https://www.npmjs.com/package/alien-signals) — 本パッケージが基盤とするシグナルエンジン。
+- [@preact/signals-core](https://www.npmjs.com/package/@preact/signals-core) — ベンチマークの比較対象。
+- [@preact/signals-react](https://www.npmjs.com/package/@preact/signals-react) — `useSignals()` boundaryのstore protocol設計における先行事例。詳細は[Prior art](docs/design/use-signals-boundary-design.ja.md#先行事例)を参照。

package/README.md

@@ -0,0 +1,54 @@
+# react-fine-grained-signals
+
+[English](README.md) | [日本語](README.ja.md)
+
+An experimental fine-grained rendering layer for React 19, built on [alien-signals](https://www.npmjs.com/package/alien-signals). It provides small reactive primitives, React hooks, and an opt-in JSX runtime for a deliberately narrow set of direct DOM bindings.
+
+**Requires React 19 or newer.** The JSX runtime uses callback-ref cleanup, which is unavailable in React 18.
+
+## Documentation
+
+See [`docs/README.md`](docs/README.md) for guides on using the library, design investigation memos, and the full documentation index.
+
+## Installation
+
+```sh
+# Planned package name — it is not published to npm yet.
+pnpm add react-fine-grained-signals alien-signals
+```
+
+`alien-signals` is a peer dependency, so install it alongside this package.
+
+The optional build plugin for automatic `useSignals()` insertion is installed separately — see [Rendering optimization](docs/rendering-optimization.md).
+
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+To verify the packed ESM packages from a clean Vite consumer (without workspace
+aliases), run:
+
+```sh
+pnpm test:consumer
+```
+
+The browser proof of concept renders the app on the server, hydrates it with React 19, and exercises direct signal bindings in Chromium:
+
+```sh
+pnpm exec playwright install --only-shell chromium
+pnpm prepare:e2e
+pnpm test:browser
+```
+
+Run `pnpm dev:browser` to build the transform package and inspect the same example at `http://127.0.0.1:4173`.
+
+## Acknowledgments
+
+- [alien-signals](https://www.npmjs.com/package/alien-signals) — the signal engine this package builds on.
+- [@preact/signals-core](https://www.npmjs.com/package/@preact/signals-core) — benchmark comparison target.
+- [@preact/signals-react](https://www.npmjs.com/package/@preact/signals-react) — prior art for the `useSignals()` boundary's store protocol; see [Prior art](docs/design/use-signals-boundary-design.md#prior-art).

package/dist/base-BZTnpU8U.js

@@ -0,0 +1,286 @@
+import { a as untrackedRender, n as hasActiveRenderCollector, t as RenderSubscription } from "./render-tracking-DCzw57BW.js";
+import { computed, effect, endBatch, getActiveSub, setActiveSub, signal, startBatch, trigger } from "alien-signals";
+//#region src/core/base.ts
+const signalInstances = /* @__PURE__ */ new WeakSet();
+/**
+* Cross-instance signal brand. `Symbol.for` resolves through the registry that
+* is shared by every realm, so a signal made by a duplicate copy of this
+* package (pnpm hoisting, a monorepo consumer, an ESM/CJS split) or in another
+* realm (iframe, worker) still answers `isSignal`. Shared with the deep-signal
+* proxy only; the package's public API stays `isSignal`.
+*/
+const SIGNAL_BRAND = Symbol.for("react-fine-grained-signals.signal");
+const SIGNAL_BRAND_VERSION = 1;
+const SIGNAL_BRAND_MIN_VERSION = 1;
+/** Marks an internal signal implementation for the public identity guard. */
+function registerSignal(value) {
+	signalInstances.add(value);
+	Object.defineProperty(value, SIGNAL_BRAND, {
+		value: SIGNAL_BRAND_VERSION,
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	return value;
+}
+/** Returns whether a value came from this package's signal APIs, any copy. */
+function isSignal(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (signalInstances.has(value)) return true;
+	const brand = value[SIGNAL_BRAND];
+	if (typeof brand !== "number" || brand < SIGNAL_BRAND_MIN_VERSION) return false;
+	return typeof value.peek === "function";
+}
+/** Internal writable signal implementation shared with deep signals. */
+var SignalImpl = class {
+	#source;
+	#renderSubscription = new RenderSubscription();
+	#currentValue;
+	#watchedSinceWrite = false;
+	constructor(initialValue) {
+		this.#source = signal(initialValue);
+		this.#currentValue = initialValue;
+	}
+	/**
+	* Records that this signal was read while some subscriber (an alien-signals
+	* effect/computed, or a React render collector) was active. Cleared by the
+	* next write, so after that write's flush has drained, a still-false flag
+	* means every reactive subscriber has re-run without re-reading this signal
+	* and has therefore been unlinked from it.
+	*/
+	markWatched() {
+		this.#watchedSinceWrite = true;
+	}
+	/**
+	* Conservative "somebody still depends on me" test used to decide whether a
+	* `deepSignal` per-key version signal is safe to drop. Never reports `false`
+	* for a signal that still has a live dependent: the React side is exact
+	* (`hasListeners`), and the alien-signals side is covered by `markWatched`,
+	* whose flag can only be `false` once a write has notified every subscriber
+	* and none of them read this signal again.
+	*/
+	hasSubscribers() {
+		return this.#watchedSinceWrite || this.#renderSubscription.hasListeners();
+	}
+	get value() {
+		if (this.#renderSubscription.track()) return this.#currentValue;
+		this.#source();
+		return this.#currentValue;
+	}
+	set value(nextValue) {
+		if (Object.is(this.#currentValue, nextValue)) return;
+		const requiresManualTrigger = this.#currentValue === nextValue;
+		this.#currentValue = nextValue;
+		this.#watchedSinceWrite = false;
+		try {
+			if (requiresManualTrigger) trigger(this.#source);
+			else this.#source(nextValue);
+		} finally {
+			this.#renderSubscription.notify();
+		}
+	}
+	peek() {
+		return this.#currentValue;
+	}
+};
+/** Creates a writable reactive value. */
+function signal$1(initialValue) {
+	return registerSignal(new SignalImpl(initialValue));
+}
+/** Unwraps a computed's box, rethrowing a cached getter error on read. */
+function unbox(box) {
+	if ("error" in box) throw box.error;
+	return box.value;
+}
+/** Creates a lazily evaluated reactive value. */
+function computed$1(getter) {
+	const source = computed((previous) => {
+		try {
+			const value = getter();
+			return previous !== void 0 && "value" in previous && Object.is(previous.value, value) ? previous : { value };
+		} catch (error) {
+			return { error };
+		}
+	});
+	let disposeRenderBridge;
+	let isInitialBridgeRun = true;
+	let lastRenderValue;
+	const renderSubscription = new RenderSubscription(() => {
+		isInitialBridgeRun = true;
+		disposeRenderBridge = effect(() => {
+			const nextValue = untrackedRender(source);
+			const changedSinceRender = lastRenderValue !== void 0 && nextValue !== lastRenderValue;
+			lastRenderValue = nextValue;
+			if (isInitialBridgeRun) {
+				isInitialBridgeRun = false;
+				if (changedSinceRender) renderSubscription.bumpVersion();
+			} else if (changedSinceRender) renderSubscription.notify();
+		});
+	}, () => {
+		disposeRenderBridge?.();
+		disposeRenderBridge = void 0;
+	});
+	return registerSignal({
+		get value() {
+			if (hasActiveRenderCollector()) {
+				const nextValue = untracked(() => untrackedRender(source));
+				if (lastRenderValue !== void 0 && nextValue !== lastRenderValue) renderSubscription.bumpVersion();
+				lastRenderValue = nextValue;
+				renderSubscription.track();
+				return unbox(nextValue);
+			}
+			return unbox(source());
+		},
+		peek() {
+			return unbox(untracked(() => source()));
+		}
+	});
+}
+/**
+* Reports an error thrown by an `effect()` callback — its body or its cleanup —
+* without letting it escape into the flush that ran it.
+*
+* alien-signals' `flush()` drains the rest of its effect queue in a `finally`
+* *without running those effects*, so one throwing effect silently cancels
+* every effect still queued behind it in that cycle — an unrelated binding, or
+* a `useSignals()`-tracked component's commit, quietly missing an update — and
+* then propagates out of whatever write triggered the flush (an event handler,
+* anywhere). Catching here keeps the failure local to this one effect.
+*
+* The policy is *report, never re-raise*, matching the two other reporters in
+* this codebase (`readBoundSignal` in src/runtime/jsx.ts and `notifyListener`
+* in src/core/render-tracking.ts):
+*
+* 1. Always `console.error(message, { cause })` — the package-wide reporting
+*    shape; assert against `mock.calls[i][1].cause` in tests.
+* 2. Then hand the error to `reportError()` when the host defines it, so
+*    `window.onerror` / `addEventListener("error")` / a telemetry SDK still see
+*    the failure. `reportError` *dispatches an error event* rather than
+*    throwing, so it reports exactly like an uncaught error while remaining
+*    non-fatal by construction.
+*
+* Both hooks are host-controlled, so **everything in this function runs inside a
+* `try`/`catch`, property lookups included**. A host can legitimately make
+* `console.error` throw (some React test setups install a throwing one to make
+* warnings fatal) or expose `reportError` as a throwing getter; either would
+* otherwise re-raise out of the reporter itself and cancel the rest of the
+* flush — precisely the failure this function exists to prevent. The two steps
+* get separate guards rather than one shared one, so a broken `console.error`
+* still leaves the `reportError` channel to surface the error, and vice versa.
+*
+* What this deliberately no longer does is `queueMicrotask(() => { throw })`.
+* That reads like a browser-only "let it reach `window.onerror`" trick, but a
+* throw out of a microtask is not a recoverable event outside a browser: in
+* Node it raises `uncaughtException`, which by default **terminates the
+* process** (verified on Node 24.19: exit code 1). Every server-side consumer —
+* SSR data plumbing, a Node script, a test harness — got an unrecoverable crash
+* from an effect body that a plain `try`/`catch` would have handled, and
+* because the throw was deferred out of the write, nothing could catch it
+* anywhere. `reportError` is not a fallback for that on Node: it is the WHATWG
+* reporting API, implemented by browsers, Web Workers, Deno, and Bun, but not
+* defined by Node at any version this package supports (absent on Node 24 LTS,
+* still not listed in the Node 26 globals docs). The feature check below is
+* therefore the whole story — where it fails, step 1 is the report.
+*
+* The failure therefore never propagates to the write that triggered it, and
+* that containment covers *synchronous* throws from the body and the cleanup.
+* An `async` effect body that rejects is a different channel this cannot reach
+* (an unhandled rejection, still fatal by default on Node), so `await`ed work
+* needs its own `try`/`catch`. Either way, code that wants to handle its own
+* failure should do so at the real failure site — inside the effect body or
+* cleanup — which is always possible and is where the `try`/`catch` belongs.
+*/
+function reportEffectError(error) {
+	try {
+		console.error("react-fine-grained-signals: an effect() callback threw; the error is contained and reported here so this flush can finish.", { cause: error });
+	} catch {}
+	try {
+		const report = globalThis.reportError;
+		if (typeof report === "function") report.call(globalThis, error);
+	} catch {}
+}
+/**
+* Wraps the cleanup an effect body returned so a throw out of it is contained
+* exactly like a throw out of the body.
+*
+* alien-signals stores the returned cleanup on the effect node and calls it
+* through its own private `runCleanup`, from two places this package cannot
+* intercept (verified against alien-signals@3.2.1):
+*
+* - `run()` calls it *before* re-running the body, i.e. inside `flush()`'s
+*   `try`, so a throw there hits the very same queue-cancelling failure mode
+*   `reportEffectError` exists for — worse, in fact, because it aborts the
+*   flush before this effect's own body has even re-run.
+* - `effectOper()` calls it on disposal — both the disposer returned below and
+*   the `unwatched` hook alien-signals fires when a nested effect loses its
+*   last subscriber, which happens during `unlink`/`purgeDeps` and so can also
+*   land in the middle of a flush.
+*
+* Neither call site is reachable from outside the module, so the guard goes on
+* the cleanup itself, on its way back to alien-signals: one wrapper covers
+* every path that can invoke it, now and later. The wrapper never rethrows, so
+* alien-signals always sees the cleanup return normally and its own
+* bookkeeping (`e.cleanup = undefined`, `activeSub` restore, the flags check
+* after `runCleanup`) stays on the success path.
+*/
+function guardCleanup(cleanup) {
+	return () => {
+		try {
+			cleanup();
+		} catch (error) {
+			reportEffectError(error);
+		}
+	};
+}
+/** Runs a reactive side effect and returns a disposer. */
+function effect$1(fn) {
+	let disposed = false;
+	let disposeEffect;
+	disposeEffect = effect(() => {
+		if (disposed) return;
+		let cleanup;
+		try {
+			cleanup = untrackedRender(fn);
+		} catch (error) {
+			reportEffectError(error);
+			return;
+		}
+		if (cleanup === void 0) return;
+		const guardedCleanup = guardCleanup(cleanup);
+		if (disposed) {
+			untracked(guardedCleanup);
+			return;
+		}
+		return guardedCleanup;
+	});
+	return () => {
+		if (disposed) return;
+		disposed = true;
+		disposeEffect?.();
+	};
+}
+/** Groups writes, deferring effect notifications until the callback completes. */
+function batch(fn) {
+	startBatch();
+	try {
+		return fn();
+	} finally {
+		endBatch();
+	}
+}
+/** Runs a callback without collecting reactive dependencies. */
+function untracked(fn) {
+	return untrackedRender(() => {
+		const activeSub = getActiveSub();
+		setActiveSub();
+		try {
+			return fn();
+		} finally {
+			setActiveSub(activeSub);
+		}
+	});
+}
+//#endregion
+export { effect$1 as a, signal$1 as c, computed$1 as i, untracked as l, SignalImpl as n, isSignal as o, batch as r, registerSignal as s, SIGNAL_BRAND as t };
+
+//# sourceMappingURL=base-BZTnpU8U.js.map

package/dist/base-BZTnpU8U.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-BZTnpU8U.js","names":["createSignal","signal","computed","createComputed","createEffect","effect"],"sources":["../src/core/base.ts"],"sourcesContent":["import {\n  computed as createComputed,\n  effect as createEffect,\n  endBatch,\n  getActiveSub,\n  setActiveSub,\n  signal as createSignal,\n  startBatch,\n  trigger,\n} from \"alien-signals\";\nimport {\n  hasActiveRenderCollector,\n  RenderSubscription,\n  untrackedRender,\n} from \"./render-tracking.js\";\n\n/** A readable reactive value. */\nexport interface ReadonlySignal<T> {\n  readonly value: T;\n  peek(): T;\n}\n\n/** A readable and writable reactive value. */\nexport interface Signal<T> extends ReadonlySignal<T> {\n  value: T;\n}\n\nconst signalInstances = new WeakSet<object>();\n\n/**\n * Cross-instance signal brand. `Symbol.for` resolves through the registry that\n * is shared by every realm, so a signal made by a duplicate copy of this\n * package (pnpm hoisting, a monorepo consumer, an ESM/CJS split) or in another\n * realm (iframe, worker) still answers `isSignal`. Shared with the deep-signal\n * proxy only; the package's public API stays `isSignal`.\n */\nexport const SIGNAL_BRAND: unique symbol = Symbol.for(\"react-fine-grained-signals.signal\");\n// The brand carries a protocol version instead of `true` so a future instance\n// can tell which contract a foreign signal claims. A version only ever widens\n// the `{ value, peek() }` contract; a breaking change must take a new symbol\n// key, which is why anything from the minimum upwards is trusted here.\nconst SIGNAL_BRAND_VERSION = 1;\nconst SIGNAL_BRAND_MIN_VERSION = 1;\n\n/** Marks an internal signal implementation for the public identity guard. */\nexport function registerSignal<T extends object>(value: T): T {\n  signalInstances.add(value);\n  // Non-enumerable keeps the brand out of JSON, `Object.keys`, spread, and\n  // React's prop diffing; non-writable and non-configurable keep it from being\n  // retargeted or stripped once the value is public. The hardening is free:\n  // measured against a writable/configurable descriptor the cost is identical,\n  // because it is the `defineProperty` call itself, and V8 keeps the instance\n  // in fast properties either way (checked with `%HasFastProperties`). Stamping\n  // the prototype instead would be worse — that pushes the prototype into\n  // dictionary mode, which every lookup through it then pays for.\n  Object.defineProperty(value, SIGNAL_BRAND, {\n    value: SIGNAL_BRAND_VERSION,\n    enumerable: false,\n    writable: false,\n    configurable: false,\n  });\n  return value;\n}\n\n/** Returns whether a value came from this package's signal APIs, any copy. */\nexport function isSignal(value: unknown): value is ReadonlySignal<unknown> {\n  if (typeof value !== \"object\" || value === null) return false;\n  // The WeakSet is both the cheaper lookup and the authority for values created\n  // by this instance; the brand is the fallback for every other instance.\n  if (signalInstances.has(value)) return true;\n  const brand = (value as { [SIGNAL_BRAND]?: unknown })[SIGNAL_BRAND];\n  if (typeof brand !== \"number\" || brand < SIGNAL_BRAND_MIN_VERSION) return false;\n  // A foreign brand is a claim, not a proof. Checking the cheap half of the\n  // contract turns a malformed brand into `false` instead of a crash inside a\n  // render, and costs nothing on the local-instance path above.\n  return typeof (value as ReadonlySignal<unknown>).peek === \"function\";\n}\n\n/** Internal writable signal implementation shared with deep signals. */\nexport class SignalImpl<T> implements Signal<T> {\n  readonly #source: ReturnType<typeof createSignal<T>>;\n  readonly #renderSubscription = new RenderSubscription();\n  #currentValue: T;\n  // Liveness bookkeeping for `deepSignal`'s per-key metadata pruning; see\n  // `markWatched`/`hasSubscribers` below. Not maintained on the read path\n  // itself — `deepSignal`'s `track()` already knows whether a subscriber is\n  // active and calls `markWatched()` there, so ordinary reads pay nothing.\n  #watchedSinceWrite = false;\n\n  constructor(initialValue: T) {\n    this.#source = createSignal(initialValue);\n    this.#currentValue = initialValue;\n  }\n\n  /**\n   * Records that this signal was read while some subscriber (an alien-signals\n   * effect/computed, or a React render collector) was active. Cleared by the\n   * next write, so after that write's flush has drained, a still-false flag\n   * means every reactive subscriber has re-run without re-reading this signal\n   * and has therefore been unlinked from it.\n   */\n  markWatched(): void {\n    this.#watchedSinceWrite = true;\n  }\n\n  /**\n   * Conservative \"somebody still depends on me\" test used to decide whether a\n   * `deepSignal` per-key version signal is safe to drop. Never reports `false`\n   * for a signal that still has a live dependent: the React side is exact\n   * (`hasListeners`), and the alien-signals side is covered by `markWatched`,\n   * whose flag can only be `false` once a write has notified every subscriber\n   * and none of them read this signal again.\n   */\n  hasSubscribers(): boolean {\n    return this.#watchedSinceWrite || this.#renderSubscription.hasListeners();\n  }\n\n  get value(): T {\n    if (this.#renderSubscription.track()) return this.#currentValue;\n    // The call records the dependency; `#currentValue` preserves Object.is\n    // semantics where the underlying callable API treats 0 and -0 alike.\n    this.#source();\n    return this.#currentValue;\n  }\n\n  set value(nextValue: T) {\n    if (Object.is(this.#currentValue, nextValue)) return;\n    const requiresManualTrigger = this.#currentValue === nextValue;\n    this.#currentValue = nextValue;\n    // Every subscriber is about to be notified, so each one either re-reads\n    // this signal (setting the flag again through `markWatched`) or drops its\n    // link to it. See `hasSubscribers`.\n    this.#watchedSinceWrite = false;\n    // The alien-signals write below flushes effects synchronously, so it can\n    // still throw even though `effect()` now contains both its body and its\n    // cleanup: anything else sharing this graph (an alien-signals effect\n    // created directly, a computed's render bridge) is outside that guard.\n    // `#currentValue` is already committed at that point, so skipping the\n    // React-side notification would\n    // leave every subscribed `RenderStore` believing the old value is still\n    // current — a permanently stale UI that no later write can repair,\n    // because a subsequent write compares against the already-updated\n    // `#currentValue`. `finally` keeps React in sync no matter how the flush\n    // exits, and still lets the original error propagate to the writer.\n    try {\n      if (requiresManualTrigger) {\n        trigger(this.#source);\n      } else {\n        this.#source(nextValue);\n      }\n    } finally {\n      this.#renderSubscription.notify();\n    }\n  }\n\n  peek(): T {\n    return this.#currentValue;\n  }\n}\n\n/** Creates a writable reactive value. */\nexport function signal<T>(initialValue: T): Signal<T> {\n  return registerSignal(new SignalImpl(initialValue));\n}\n\n/** A computed's cached result, boxed so a thrown error can be cached too. */\ntype ComputedBox<T> = { value: T } | { error: unknown };\n\n/** Unwraps a computed's box, rethrowing a cached getter error on read. */\nfunction unbox<T>(box: ComputedBox<T>): T {\n  if (\"error\" in box) throw box.error;\n  return box.value;\n}\n\n/** Creates a lazily evaluated reactive value. */\nexport function computed<T>(getter: () => T): ReadonlySignal<T> {\n  // alien-signals' `updateComputed` resets its dirty/pending flags in a\n  // `finally` no matter how the callback exits, so a thrown getter leaves the\n  // node looking clean with its stale cached value, and can permanently\n  // unwatch an effect whose run was interrupted mid-flush (verified against\n  // alien-signals@3.2.1: neither the computed nor the effect ever recovers on\n  // a later write). Catching here keeps the callback always returning\n  // normally, so alien-signals' own bookkeeping stays on the success path;\n  // the error is boxed and only rethrown when something reads `.value` or\n  // `.peek()`, which for React happens during render where an Error Boundary\n  // can catch it (mirrors `createDeepSelectorStore` in `src/react/hooks.ts`).\n  const source = createComputed<ComputedBox<T>>((previous) => {\n    try {\n      const value = getter();\n      // Guard `\"value\" in previous`: if `previous` is an error box, its\n      // `.value` is `undefined`, so without this a legitimate recovery to\n      // `value === undefined` would `Object.is` that against `undefined` and\n      // wrongly keep returning the stale error box.\n      return previous !== undefined && \"value\" in previous && Object.is(previous.value, value)\n        ? previous\n        : { value };\n    } catch (error) {\n      return { error };\n    }\n  });\n  let disposeRenderBridge: (() => void) | undefined;\n  let isInitialBridgeRun = true;\n  let lastRenderValue: ComputedBox<T> | undefined;\n  const renderSubscription = new RenderSubscription(\n    () => {\n      isInitialBridgeRun = true;\n      disposeRenderBridge = createEffect(() => {\n        const nextValue = untrackedRender(source);\n        const changedSinceRender =\n          lastRenderValue !== undefined && nextValue !== lastRenderValue;\n        lastRenderValue = nextValue;\n        if (isInitialBridgeRun) {\n          isInitialBridgeRun = false;\n          if (changedSinceRender) renderSubscription.bumpVersion();\n        } else if (changedSinceRender) {\n          renderSubscription.notify();\n        }\n      });\n    },\n    () => {\n      disposeRenderBridge?.();\n      disposeRenderBridge = undefined;\n    },\n  );\n\n  const result: ReadonlySignal<T> = {\n    get value(): T {\n      if (hasActiveRenderCollector()) {\n        const nextValue = untracked(() => untrackedRender(source));\n        if (lastRenderValue !== undefined && nextValue !== lastRenderValue) {\n          renderSubscription.bumpVersion();\n        }\n        lastRenderValue = nextValue;\n        // Track after evaluating so this render records the post-evaluation\n        // version without masking an older concurrent render.\n        renderSubscription.track();\n        return unbox(nextValue);\n      }\n      return unbox(source());\n    },\n    // `peek()` is documented as an untracked read, not an error-suppressing\n    // one, so it rethrows the same as `.value` — consistent with\n    // `useDeepSignalValue`, whose selector errors always surface on read.\n    peek(): T {\n      return unbox(untracked(() => source()));\n    },\n  };\n  return registerSignal(result);\n}\n\n/**\n * Reports an error thrown by an `effect()` callback — its body or its cleanup —\n * without letting it escape into the flush that ran it.\n *\n * alien-signals' `flush()` drains the rest of its effect queue in a `finally`\n * *without running those effects*, so one throwing effect silently cancels\n * every effect still queued behind it in that cycle — an unrelated binding, or\n * a `useSignals()`-tracked component's commit, quietly missing an update — and\n * then propagates out of whatever write triggered the flush (an event handler,\n * anywhere). Catching here keeps the failure local to this one effect.\n *\n * The policy is *report, never re-raise*, matching the two other reporters in\n * this codebase (`readBoundSignal` in src/runtime/jsx.ts and `notifyListener`\n * in src/core/render-tracking.ts):\n *\n * 1. Always `console.error(message, { cause })` — the package-wide reporting\n *    shape; assert against `mock.calls[i][1].cause` in tests.\n * 2. Then hand the error to `reportError()` when the host defines it, so\n *    `window.onerror` / `addEventListener(\"error\")` / a telemetry SDK still see\n *    the failure. `reportError` *dispatches an error event* rather than\n *    throwing, so it reports exactly like an uncaught error while remaining\n *    non-fatal by construction.\n *\n * Both hooks are host-controlled, so **everything in this function runs inside a\n * `try`/`catch`, property lookups included**. A host can legitimately make\n * `console.error` throw (some React test setups install a throwing one to make\n * warnings fatal) or expose `reportError` as a throwing getter; either would\n * otherwise re-raise out of the reporter itself and cancel the rest of the\n * flush — precisely the failure this function exists to prevent. The two steps\n * get separate guards rather than one shared one, so a broken `console.error`\n * still leaves the `reportError` channel to surface the error, and vice versa.\n *\n * What this deliberately no longer does is `queueMicrotask(() => { throw })`.\n * That reads like a browser-only \"let it reach `window.onerror`\" trick, but a\n * throw out of a microtask is not a recoverable event outside a browser: in\n * Node it raises `uncaughtException`, which by default **terminates the\n * process** (verified on Node 24.19: exit code 1). Every server-side consumer —\n * SSR data plumbing, a Node script, a test harness — got an unrecoverable crash\n * from an effect body that a plain `try`/`catch` would have handled, and\n * because the throw was deferred out of the write, nothing could catch it\n * anywhere. `reportError` is not a fallback for that on Node: it is the WHATWG\n * reporting API, implemented by browsers, Web Workers, Deno, and Bun, but not\n * defined by Node at any version this package supports (absent on Node 24 LTS,\n * still not listed in the Node 26 globals docs). The feature check below is\n * therefore the whole story — where it fails, step 1 is the report.\n *\n * The failure therefore never propagates to the write that triggered it, and\n * that containment covers *synchronous* throws from the body and the cleanup.\n * An `async` effect body that rejects is a different channel this cannot reach\n * (an unhandled rejection, still fatal by default on Node), so `await`ed work\n * needs its own `try`/`catch`. Either way, code that wants to handle its own\n * failure should do so at the real failure site — inside the effect body or\n * cleanup — which is always possible and is where the `try`/`catch` belongs.\n */\nfunction reportEffectError(error: unknown): void {\n  try {\n    console.error(\n      \"react-fine-grained-signals: an effect() callback threw; the error is contained and reported here so this flush can finish.\",\n      { cause: error },\n    );\n  } catch {\n    // A host that made `console.error` itself throw does not get to turn a\n    // contained effect failure back into one that escapes and kills the flush.\n  }\n  try {\n    // Looked up per call, not captured at module load, so a host (or a test)\n    // that installs its own `reportError` later is still honored — and read\n    // inside the guard, because the property itself can be a throwing getter.\n    const report = (globalThis as { reportError?: (error: unknown) => void }).reportError;\n    if (typeof report === \"function\") report.call(globalThis, error);\n  } catch {\n    // Same rule for the second hook: a host whose `reportError` throws must not\n    // break containment either. The error already went to the console above.\n  }\n}\n\n/**\n * Wraps the cleanup an effect body returned so a throw out of it is contained\n * exactly like a throw out of the body.\n *\n * alien-signals stores the returned cleanup on the effect node and calls it\n * through its own private `runCleanup`, from two places this package cannot\n * intercept (verified against alien-signals@3.2.1):\n *\n * - `run()` calls it *before* re-running the body, i.e. inside `flush()`'s\n *   `try`, so a throw there hits the very same queue-cancelling failure mode\n *   `reportEffectError` exists for — worse, in fact, because it aborts the\n *   flush before this effect's own body has even re-run.\n * - `effectOper()` calls it on disposal — both the disposer returned below and\n *   the `unwatched` hook alien-signals fires when a nested effect loses its\n *   last subscriber, which happens during `unlink`/`purgeDeps` and so can also\n *   land in the middle of a flush.\n *\n * Neither call site is reachable from outside the module, so the guard goes on\n * the cleanup itself, on its way back to alien-signals: one wrapper covers\n * every path that can invoke it, now and later. The wrapper never rethrows, so\n * alien-signals always sees the cleanup return normally and its own\n * bookkeeping (`e.cleanup = undefined`, `activeSub` restore, the flags check\n * after `runCleanup`) stays on the success path.\n */\nfunction guardCleanup(cleanup: () => void): () => void {\n  return () => {\n    try {\n      cleanup();\n    } catch (error) {\n      reportEffectError(error);\n    }\n  };\n}\n\n/** Runs a reactive side effect and returns a disposer. */\nexport function effect(fn: () => void | (() => void)): () => void {\n  let disposed = false;\n  let disposeEffect: (() => void) | undefined;\n  disposeEffect = createEffect(() => {\n    if (disposed) return;\n    let cleanup: void | (() => void);\n    try {\n      cleanup = untrackedRender(fn);\n    } catch (error) {\n      reportEffectError(error);\n      return;\n    }\n    if (cleanup === undefined) return;\n    const guardedCleanup = guardCleanup(cleanup);\n    if (disposed) {\n      untracked(guardedCleanup);\n      return;\n    }\n    return guardedCleanup;\n  });\n  return () => {\n    if (disposed) return;\n    disposed = true;\n    disposeEffect?.();\n  };\n}\n\n/** Groups writes, deferring effect notifications until the callback completes. */\nexport function batch<T>(fn: () => T): T {\n  startBatch();\n  try {\n    return fn();\n  } finally {\n    endBatch();\n  }\n}\n\n/** Runs a callback without collecting reactive dependencies. */\nexport function untracked<T>(fn: () => T): T {\n  return untrackedRender(() => {\n    const activeSub = getActiveSub();\n    setActiveSub();\n    try {\n      return fn();\n    } finally {\n      setActiveSub(activeSub);\n    }\n  });\n}\n"],"mappings":"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"}

package/dist/base-Bx5ahfW2.d.ts

@@ -0,0 +1,24 @@
+//#region src/core/base.d.ts
+/** A readable reactive value. */
+interface ReadonlySignal<T> {
+  readonly value: T;
+  peek(): T;
+}
+/** A readable and writable reactive value. */
+interface Signal<T> extends ReadonlySignal<T> {
+  value: T;
+}
+/** Returns whether a value came from this package's signal APIs, any copy. */
+declare function isSignal(value: unknown): value is ReadonlySignal<unknown>;
+/** Creates a writable reactive value. */
+declare function signal<T>(initialValue: T): Signal<T>;
+/** Creates a lazily evaluated reactive value. */
+declare function computed<T>(getter: () => T): ReadonlySignal<T>;
+/** Runs a reactive side effect and returns a disposer. */
+declare function effect(fn: () => void | (() => void)): () => void;
+/** Groups writes, deferring effect notifications until the callback completes. */
+declare function batch<T>(fn: () => T): T;
+/** Runs a callback without collecting reactive dependencies. */
+declare function untracked<T>(fn: () => T): T;
+//#endregion
+export { effect as a, untracked as c, computed as i, Signal as n, isSignal as o, batch as r, signal as s, ReadonlySignal as t };