@signal-kernel/core 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,331 @@
+# `@signal-kernel/core`
+### A minimal, deterministic, fine-grained reactivity engine.
+
+`@signal-kernel/core` provides the foundational primitives for building reactive systems:
+signals, computed values, effects, a deterministic scheduler, and a dependency graph.
+
+This package is framework-agnostic and has no DOM or framework dependencies, making it suitable for:
+- UI frameworks (via adapters)  
+- Server-side reactive pipelines  
+- Async dataflow runtimes  
+- State machines & reactive graphs  
+- Compiler-driven reactivity transforms  
+
+It is the core runtime powering the broader Signal Kernel ecosystem.
+
+---
+
+# Installation
+```bash
+npm install @signal-kernel/core
+```
+
+---
+
+# Overview
+`@signal-kernel/core` implements a modern fine-grained reactive graph, consisting of:
+
+1. **`signal()`**
+    Mutable state unit, with dependency tracking and change propagation.  
+2. **`computed()`**
+    Lazy, memoized derivations with automatic dependency tracking.  
+3. **`createEffect()`**
+    Reactive side-effects with cleanup, disposal, and deterministic scheduling.  
+4. **`batch()`**
+    Coalesces multiple updates into a single scheduler flush.  
+5. **Deterministic Scheduler**
+    A two-phase flush model that first stabilizes computed nodes, then executes effects.  
+
+All primitives are minimal yet expressive enough to build a complete reactivity system or compose higher-level runtimes (e.g., async pipelines).
+
+---
+
+# Public API
+```ts
+export { signal } from "./signal.js";
+export { computed } from "./computed.js";
+export { createEffect, onCleanup } from "./effect.js";
+export { batch } from "./scheduler.js";
+```
+
+*(Internal APIs such as `atomic()`, `transaction()`, and `flushSync()` are intentionally not exported at this stage.)*
+
+---
+---------------------------------------------------------
+# 1. `signal()`
+---------------------------------------------------------
+
+### Signature
+```ts
+const { get, set, subscribe, peek } = signal<T>(initial, equals?);
+```
+
+### Behavior
+`get()`  
+- Returns the current value.  
+- If called within an active observer, registers a dependency via track().  
+
+`set(next)`  
+- Updates the stored value.  
+- Uses a customizable equality comparator to prevent unnecessary propagation.  
+- Notifies downstream:
+    - computed nodes → marked stale  
+    - effects → scheduled for execution  
+
+`peek()`  
+- Reads value without tracking dependencies.  
+
+`subscribe(node)`  
+Manually links an observer to the signal.
+Useful for framework adapters (React/Vue/Solid) that manage their own lifecycle.  
+
+**Key properties**  
+- Signals **cannot depend** on others (enforced by runtime errors).  
+- They are the leaf nodes of the reactive graph.  
+- Changes propagate deterministically through the scheduler.  
+
+---
+
+---------------------------------------------------------
+# 2. `computed()`
+---------------------------------------------------------
+### Signature
+```ts
+const { get, peek, dispose } = computed<T>(fn, equals?);
+```
+
+### Behavior
+##### Lazy evaluation
+Computed values only evaluate when `get()` is called.
+If the node is stale—or has never computed before—it runs its `fn()` and updates dependencies.
+
+##### Automatic dependency tracking
+During execution, all accessed signals/computeds are recorded via `track()`.
+
+##### Memoization & equality
+A computed node only updates its value when:  
+```rs
+!equals(prev, next)
+```
+
+##### Stale propagation
+When an upstream signal or computed changes:  
+```ts
+computed.stale = true;
+```
+
+Downstream effects are scheduled, but computation still occurs lazily.
+
+##### Cycle detection
+If a computed re-enters itself:  
+```ts
+throw new Error("Cycle detected in computed");
+```
+
+`dispose()`  
+Fully removes the node from the graph:  
+- Unlinks all deps and subs  
+- Clears cached value  
+- Leaves the graph consistent  
+
+---
+
+---------------------------------------------------------
+# 3. `createEffect()`
+---------------------------------------------------------
+Effects are the imperative “side-effect” layer of the reactive system.
+
+### Signature
+```ts
+const dispose = createEffect(() => {
+  // ...
+  return () => cleanup();
+});
+```
+
+### Behavior
+
+##### Automatic dependency tracking
+During effect execution, reads from signals or computed values create graph edges via `track()`.
+
+##### Cleanup handling
+Before each re-run:  
+1. All previous cleanups run  
+2. All previous dependencies are removed  
+3. The effect function re-executes and re-establishes its dependencies  
+
+##### Disposal
+Calling `dispose()`:  
+- Runs remaining cleanups  
+- Deletes the effect from the registry  
+- Removes all graph links  
+- Prevents future scheduling  
+
+##### Integration with scheduler
+Effects are not run synchronously—they are **scheduled**.
+This ensures deterministic ordering and batching behavior.
+
+---
+
+---------------------------------------------------------
+# 4. Scheduler
+---------------------------------------------------------
+
+Your runtime's scheduler is a defining feature.
+It implements a two-phase deterministic flush, ensuring stable, predictable updates.
+
+### Two-phase flush model
+```mermaid
+flowchart TD
+  A["Began flushJobsTwoPhase()"] --> B{computeQ and effectQ are empty?}
+  B -- Yes --> Z[return]
+  B -- No --> C[scheduled = false]
+
+  C --> D{computeQ is empty?}
+  D -- No --> E[deal with one computeQ]
+  E --> F["iterate job.run()<br/>Maybe enqueue a new computed/effect"]
+  F --> D
+  D -- Yes --> G[Deal with Phase B]
+
+  G --> H{effectQ is empty?}
+  H -- No --> I["Follow priority sort effectQ"]
+  I --> J["iterate effect.run()<br/>Maybe enqueue a new computed/effect"]
+  J --> K{"Have a new task?（computeQ or effectQ）"}
+  K -- Yes --> C
+  K -- No --> Z
+
+  H -- Yes --> Z
+
+```
+
+### Properties
+- Computed nodes always stabilize before effects run.  
+- Effects run in priority order.  
+- No interleaving of computed and effect execution.  
+- Infinite loops guarded by a safety counter.  
+- Batching defers flush until the outermost batch completes.  
+
+##### `batch()`
+```ts
+batch(() => {
+  setA(1);
+  setB(2);
+});
+```
+Updates are collapsed; effects execute once.
+
+##### Internal APIs (not exported)
+- `atomic()`  
+- `transaction()`  
+- `flushSync()`  
+
+These provide:  
+- nested transaction support  
+- rollback semantics  
+- temporary scheduler muting  
+- consistent reconciling of reactive state  
+
+They are intentionally excluded from the public API until higher-level packages require them.
+
+---
+
+---------------------------------------------------------
+# 5. Dependency Graph
+---------------------------------------------------------
+From `graph.ts`, each reactive node has:  
+```ts
+kind: "signal" | "computed" | "effect"
+deps: Set<Node>
+subs: Set<Node>
+```
+
+`track(dep)`  
+Creates a directional edge:  
+observer → dep  
+
+`withObserver(observer, fn)`  
+Temporarily sets the active observer during execution.  
+
+`unlink(from, to)`  
+Removes a dependency edge; used by effects and computed nodes on re-run.  
+
+---
+
+---------------------------------------------------------
+# 6. Internal Architecture Diagram
+---------------------------------------------------------
+```mermaid
+flowchart TD
+  subgraph Core["Signal Kernel Core (Reactive Graph)"]
+    S["signal()"]
+    C["computed()"]
+    E["createEffect()"]
+  end
+
+  subgraph Scheduler["Scheduler (two-phase flush)"]
+    PA["Phase A:<br/>recompute all stale computed"]
+    PB["Phase B:<br/>run effects (by priority)"]
+  end
+
+  %% Signal update path
+  S -- "set()" --> MS["markStale(computed)"]
+  MS --> C
+
+  %% Computed recomputation
+  C -- "get() / stale" --> RC["recompute()"]
+  RC --> C
+
+  %% Effects depend on signals / computed
+  S -- "track()" --> E
+  C -- "track()" --> E
+
+  %% Scheduling
+  E -- "scheduleJob()" --> PA
+  C -. "stale" .-> PA
+
+  %% Two-phase loop
+  PA --> C
+  PA --> PB
+  PB --> E
+
+  %% New work can re-enter the loop
+  PB -. "new stale computed / effects" .-> PA
+```
+
+---
+
+---------------------------------------------------------
+# 7. Why This Runtime?
+---------------------------------------------------------
+Compared to other fine-grained reactive engines, Signal Kernel Core offers:  
+### Deterministic scheduling
+Computed nodes always settle before effects.  
+
+### Lazy derivations
+Computed values are only evaluated when needed.  
+
+### Cycle detection
+Prevents accidental recursive dependencies.  
+
+### Zero framework assumptions
+No VDOM, no compiler, no DOM APIs.  
+
+### Adapter-friendly design
+`subscribe()`, `onCleanup()`, and effect disposal make framework integration clean.  
+
+### Extensibility
+The internal architecture supports advanced features such as async pipelines, transactions, and server-side reactive graphs.  
+
+---
+
+---------------------------------------------------------
+# 8. Summary
+---------------------------------------------------------
+`@signal-kernel/core` provides a minimal yet robust foundation for building reactive systems.
+Its combination of:  
+- signals  
+- lazy computed values  
+- deterministic effects  
+- a two-phase scheduler  
+- an explicit dependency graph  
+

package/dist/index.cjs

@@ -0,0 +1,296 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  batch: () => batch,
+  computed: () => computed,
+  createEffect: () => createEffect,
+  onCleanup: () => onCleanup,
+  signal: () => signal
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/graph.ts
+function link(from, to) {
+  if (from.kind === "signal") throw new Error("Signal nodes cannot depend on others");
+  if (from.deps.has(to)) return;
+  from.deps.add(to);
+  to.subs.add(from);
+}
+function unlink(from, to) {
+  from.deps.delete(to);
+  to.subs.delete(from);
+}
+var currentObserver = null;
+function withObserver(obs, fn) {
+  const prev = currentObserver;
+  currentObserver = obs;
+  try {
+    return fn();
+  } finally {
+    currentObserver = prev;
+  }
+}
+function track(dep) {
+  if (!currentObserver) return;
+  link(currentObserver, dep);
+}
+
+// src/registry.ts
+var EffectSlot = /* @__PURE__ */ Symbol("EffectSlot");
+var SymbolRegistry = {
+  get(node) {
+    return node[EffectSlot];
+  },
+  set(node, inst) {
+    Object.defineProperty(node, EffectSlot, {
+      value: inst,
+      enumerable: false,
+      configurable: true
+    });
+  },
+  delete(node) {
+    Reflect.deleteProperty(node, EffectSlot);
+  }
+};
+
+// src/computed.ts
+var defaultEquals = Object.is;
+function markStale(node) {
+  if (node.kind !== "computed") return;
+  const c = node;
+  if (c.stale) return;
+  c.stale = true;
+  for (const sub of node.subs) {
+    if (sub.kind === "computed") {
+      markStale(sub);
+    } else if (sub.kind === "effect") {
+      SymbolRegistry.get(sub)?.schedule();
+    }
+  }
+}
+function computed(fn, equals = defaultEquals) {
+  const node = {
+    kind: "computed",
+    deps: /* @__PURE__ */ new Set(),
+    subs: /* @__PURE__ */ new Set(),
+    value: void 0,
+    stale: true,
+    equals,
+    computing: false,
+    hasValue: false
+  };
+  function recompute() {
+    if (node.computing) throw new Error("Cycle detected in computed");
+    node.computing = true;
+    for (const d of [...node.deps]) unlink(node, d);
+    const next = withObserver(node, fn);
+    if (!node.hasValue || !node.equals(node.value, next)) {
+      node.value = next;
+      node.hasValue = true;
+    }
+    node.stale = false;
+    node.computing = false;
+  }
+  const get = () => {
+    track(node);
+    if (node.stale || !node.hasValue) recompute();
+    return node.value;
+  };
+  const peek = () => node.value;
+  const dispose = () => {
+    for (const d of [...node.deps]) unlink(node, d);
+    for (const s of [...node.subs]) unlink(s, node);
+    node.deps.clear();
+    node.subs.clear();
+    node.stale = true;
+    node.hasValue = false;
+  };
+  return { get, peek, dispose };
+}
+
+// src/scheduler.ts
+var computeQ = /* @__PURE__ */ new Set();
+var effectQ = /* @__PURE__ */ new Set();
+var scheduled = false;
+var batchDepth = 0;
+var atomicDepth = 0;
+var atomicLogs = [];
+var muted = 0;
+function scheduleJob(job) {
+  const j = job;
+  if (j.disposed) return;
+  if (muted > 0) return;
+  const kind = j.kind ?? "effect";
+  if (kind === "computed") computeQ.add(j);
+  else effectQ.add(j);
+  if (!scheduled && batchDepth === 0) {
+    scheduled = true;
+    queueMicrotask(flushJobsTwoPhase);
+  }
+}
+function batch(fn) {
+  batchDepth++;
+  try {
+    return fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) flushJobsTwoPhase();
+  }
+}
+function inAtomic() {
+  return atomicDepth > 0;
+}
+function recordAtomicWrite(node, prevValue) {
+  const log = atomicLogs[atomicLogs.length - 1];
+  if (!log) return;
+  if (!log.has(node)) log.set(node, prevValue);
+}
+function flushJobsTwoPhase() {
+  scheduled = false;
+  let guard = 0;
+  while (computeQ.size > 0 || effectQ.size > 0) {
+    if (++guard > 1e4) throw new Error("Infinite update loop");
+    while (computeQ.size > 0) {
+      const batch2 = Array.from(computeQ);
+      computeQ.clear();
+      for (const job of batch2) {
+        job.kind = "computed";
+        job.run();
+      }
+    }
+    if (effectQ.size > 0) {
+      const batch2 = Array.from(effectQ).sort(
+        (a, b) => (a.priority ?? 0) - (b.priority ?? 0)
+      );
+      effectQ.clear();
+      for (const job of batch2) {
+        job.kind = "effect";
+        job.run();
+      }
+    }
+  }
+}
+
+// src/signal.ts
+var defaultEquals2 = Object.is;
+function signal(initial, equals = defaultEquals2) {
+  const node = {
+    kind: "signal",
+    deps: /* @__PURE__ */ new Set(),
+    subs: /* @__PURE__ */ new Set(),
+    value: initial,
+    equals
+  };
+  const get = () => {
+    track(node);
+    return node.value;
+  };
+  const set = (next) => {
+    const prev = node.value;
+    const nxtVal = typeof next === "function" ? next(node.value) : next;
+    if (node.equals(node.value, nxtVal)) return;
+    if (inAtomic()) recordAtomicWrite(node, prev);
+    node.value = nxtVal;
+    if (node.subs.size === 0) return;
+    for (const sub of node.subs) {
+      if (sub.kind === "effect") {
+        SymbolRegistry.get(sub)?.schedule();
+      } else if (sub.kind === "computed") {
+        markStale(sub);
+      }
+    }
+  };
+  const subscribe = (observer) => {
+    if (observer.kind === "signal") {
+      throw new Error("A signal cannot subscribe to another node");
+    }
+    link(observer, node);
+    return () => unlink(observer, node);
+  };
+  return { get, set, subscribe, peek: () => node.value };
+}
+
+// src/effect.ts
+function drainCleanups(list, onError) {
+  for (let i = list.length - 1; i >= 0; i--) {
+    const cb = list[i];
+    try {
+      cb?.();
+    } catch (e) {
+      onError?.(e);
+    }
+  }
+  list.length = 0;
+}
+var activeEffect = null;
+function onCleanup(cb) {
+  if (activeEffect) activeEffect.cleanups.push(cb);
+}
+var EffectInstance = class {
+  constructor(fn) {
+    this.fn = fn;
+    this.node = {
+      kind: "effect",
+      deps: /* @__PURE__ */ new Set(),
+      subs: /* @__PURE__ */ new Set()
+    };
+    this.cleanups = [];
+    this.disposed = false;
+    SymbolRegistry.set(this.node, this);
+  }
+  run() {
+    if (this.disposed) return;
+    drainCleanups(this.cleanups);
+    for (const dep of [...this.node.deps]) unlink(this.node, dep);
+    activeEffect = this;
+    try {
+      const ret = withObserver(this.node, this.fn);
+      if (typeof ret === "function") this.cleanups.push(ret);
+    } finally {
+      activeEffect = null;
+    }
+  }
+  schedule() {
+    scheduleJob(this);
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    drainCleanups(this.cleanups);
+    for (const dep of [...this.node.deps]) unlink(this.node, dep);
+    this.node.deps.clear();
+    SymbolRegistry.delete(this.node);
+  }
+};
+function createEffect(fn) {
+  const inst = new EffectInstance(fn);
+  inst.run();
+  return () => inst.dispose();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  batch,
+  computed,
+  createEffect,
+  onCleanup,
+  signal
+});

package/dist/index.d.cts

@@ -0,0 +1,29 @@
+type Kind = 'signal' | 'computed' | 'effect';
+interface Node {
+    kind: Kind;
+    deps: Set<Node>;
+    subs: Set<Node>;
+}
+
+type Comparator$1<T> = (a: T, b: T) => boolean;
+declare function signal<T>(initial: T, equals?: Comparator$1<T>): {
+    get: () => T;
+    set: (next: T | ((prev: T) => T)) => void;
+    subscribe: (observer: Node) => () => void;
+    peek: () => T;
+};
+
+type Comparator<T> = (a: T, b: T) => boolean;
+declare function computed<T>(fn: () => T, equals?: Comparator<T>): {
+    get: () => T;
+    peek: () => T;
+    dispose: () => void;
+};
+
+type Cleanup = () => void;
+declare function onCleanup(cb: Cleanup): void;
+declare function createEffect(fn: () => void | Cleanup): () => void;
+
+declare function batch<T>(fn: () => T): T;
+
+export { batch, computed, createEffect, onCleanup, signal };

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+type Kind = 'signal' | 'computed' | 'effect';
+interface Node {
+    kind: Kind;
+    deps: Set<Node>;
+    subs: Set<Node>;
+}
+
+type Comparator$1<T> = (a: T, b: T) => boolean;
+declare function signal<T>(initial: T, equals?: Comparator$1<T>): {
+    get: () => T;
+    set: (next: T | ((prev: T) => T)) => void;
+    subscribe: (observer: Node) => () => void;
+    peek: () => T;
+};
+
+type Comparator<T> = (a: T, b: T) => boolean;
+declare function computed<T>(fn: () => T, equals?: Comparator<T>): {
+    get: () => T;
+    peek: () => T;
+    dispose: () => void;
+};
+
+type Cleanup = () => void;
+declare function onCleanup(cb: Cleanup): void;
+declare function createEffect(fn: () => void | Cleanup): () => void;
+
+declare function batch<T>(fn: () => T): T;
+
+export { batch, computed, createEffect, onCleanup, signal };

package/dist/index.js

@@ -0,0 +1,265 @@
+// src/graph.ts
+function link(from, to) {
+  if (from.kind === "signal") throw new Error("Signal nodes cannot depend on others");
+  if (from.deps.has(to)) return;
+  from.deps.add(to);
+  to.subs.add(from);
+}
+function unlink(from, to) {
+  from.deps.delete(to);
+  to.subs.delete(from);
+}
+var currentObserver = null;
+function withObserver(obs, fn) {
+  const prev = currentObserver;
+  currentObserver = obs;
+  try {
+    return fn();
+  } finally {
+    currentObserver = prev;
+  }
+}
+function track(dep) {
+  if (!currentObserver) return;
+  link(currentObserver, dep);
+}
+
+// src/registry.ts
+var EffectSlot = /* @__PURE__ */ Symbol("EffectSlot");
+var SymbolRegistry = {
+  get(node) {
+    return node[EffectSlot];
+  },
+  set(node, inst) {
+    Object.defineProperty(node, EffectSlot, {
+      value: inst,
+      enumerable: false,
+      configurable: true
+    });
+  },
+  delete(node) {
+    Reflect.deleteProperty(node, EffectSlot);
+  }
+};
+
+// src/computed.ts
+var defaultEquals = Object.is;
+function markStale(node) {
+  if (node.kind !== "computed") return;
+  const c = node;
+  if (c.stale) return;
+  c.stale = true;
+  for (const sub of node.subs) {
+    if (sub.kind === "computed") {
+      markStale(sub);
+    } else if (sub.kind === "effect") {
+      SymbolRegistry.get(sub)?.schedule();
+    }
+  }
+}
+function computed(fn, equals = defaultEquals) {
+  const node = {
+    kind: "computed",
+    deps: /* @__PURE__ */ new Set(),
+    subs: /* @__PURE__ */ new Set(),
+    value: void 0,
+    stale: true,
+    equals,
+    computing: false,
+    hasValue: false
+  };
+  function recompute() {
+    if (node.computing) throw new Error("Cycle detected in computed");
+    node.computing = true;
+    for (const d of [...node.deps]) unlink(node, d);
+    const next = withObserver(node, fn);
+    if (!node.hasValue || !node.equals(node.value, next)) {
+      node.value = next;
+      node.hasValue = true;
+    }
+    node.stale = false;
+    node.computing = false;
+  }
+  const get = () => {
+    track(node);
+    if (node.stale || !node.hasValue) recompute();
+    return node.value;
+  };
+  const peek = () => node.value;
+  const dispose = () => {
+    for (const d of [...node.deps]) unlink(node, d);
+    for (const s of [...node.subs]) unlink(s, node);
+    node.deps.clear();
+    node.subs.clear();
+    node.stale = true;
+    node.hasValue = false;
+  };
+  return { get, peek, dispose };
+}
+
+// src/scheduler.ts
+var computeQ = /* @__PURE__ */ new Set();
+var effectQ = /* @__PURE__ */ new Set();
+var scheduled = false;
+var batchDepth = 0;
+var atomicDepth = 0;
+var atomicLogs = [];
+var muted = 0;
+function scheduleJob(job) {
+  const j = job;
+  if (j.disposed) return;
+  if (muted > 0) return;
+  const kind = j.kind ?? "effect";
+  if (kind === "computed") computeQ.add(j);
+  else effectQ.add(j);
+  if (!scheduled && batchDepth === 0) {
+    scheduled = true;
+    queueMicrotask(flushJobsTwoPhase);
+  }
+}
+function batch(fn) {
+  batchDepth++;
+  try {
+    return fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) flushJobsTwoPhase();
+  }
+}
+function inAtomic() {
+  return atomicDepth > 0;
+}
+function recordAtomicWrite(node, prevValue) {
+  const log = atomicLogs[atomicLogs.length - 1];
+  if (!log) return;
+  if (!log.has(node)) log.set(node, prevValue);
+}
+function flushJobsTwoPhase() {
+  scheduled = false;
+  let guard = 0;
+  while (computeQ.size > 0 || effectQ.size > 0) {
+    if (++guard > 1e4) throw new Error("Infinite update loop");
+    while (computeQ.size > 0) {
+      const batch2 = Array.from(computeQ);
+      computeQ.clear();
+      for (const job of batch2) {
+        job.kind = "computed";
+        job.run();
+      }
+    }
+    if (effectQ.size > 0) {
+      const batch2 = Array.from(effectQ).sort(
+        (a, b) => (a.priority ?? 0) - (b.priority ?? 0)
+      );
+      effectQ.clear();
+      for (const job of batch2) {
+        job.kind = "effect";
+        job.run();
+      }
+    }
+  }
+}
+
+// src/signal.ts
+var defaultEquals2 = Object.is;
+function signal(initial, equals = defaultEquals2) {
+  const node = {
+    kind: "signal",
+    deps: /* @__PURE__ */ new Set(),
+    subs: /* @__PURE__ */ new Set(),
+    value: initial,
+    equals
+  };
+  const get = () => {
+    track(node);
+    return node.value;
+  };
+  const set = (next) => {
+    const prev = node.value;
+    const nxtVal = typeof next === "function" ? next(node.value) : next;
+    if (node.equals(node.value, nxtVal)) return;
+    if (inAtomic()) recordAtomicWrite(node, prev);
+    node.value = nxtVal;
+    if (node.subs.size === 0) return;
+    for (const sub of node.subs) {
+      if (sub.kind === "effect") {
+        SymbolRegistry.get(sub)?.schedule();
+      } else if (sub.kind === "computed") {
+        markStale(sub);
+      }
+    }
+  };
+  const subscribe = (observer) => {
+    if (observer.kind === "signal") {
+      throw new Error("A signal cannot subscribe to another node");
+    }
+    link(observer, node);
+    return () => unlink(observer, node);
+  };
+  return { get, set, subscribe, peek: () => node.value };
+}
+
+// src/effect.ts
+function drainCleanups(list, onError) {
+  for (let i = list.length - 1; i >= 0; i--) {
+    const cb = list[i];
+    try {
+      cb?.();
+    } catch (e) {
+      onError?.(e);
+    }
+  }
+  list.length = 0;
+}
+var activeEffect = null;
+function onCleanup(cb) {
+  if (activeEffect) activeEffect.cleanups.push(cb);
+}
+var EffectInstance = class {
+  constructor(fn) {
+    this.fn = fn;
+    this.node = {
+      kind: "effect",
+      deps: /* @__PURE__ */ new Set(),
+      subs: /* @__PURE__ */ new Set()
+    };
+    this.cleanups = [];
+    this.disposed = false;
+    SymbolRegistry.set(this.node, this);
+  }
+  run() {
+    if (this.disposed) return;
+    drainCleanups(this.cleanups);
+    for (const dep of [...this.node.deps]) unlink(this.node, dep);
+    activeEffect = this;
+    try {
+      const ret = withObserver(this.node, this.fn);
+      if (typeof ret === "function") this.cleanups.push(ret);
+    } finally {
+      activeEffect = null;
+    }
+  }
+  schedule() {
+    scheduleJob(this);
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    drainCleanups(this.cleanups);
+    for (const dep of [...this.node.deps]) unlink(this.node, dep);
+    this.node.deps.clear();
+    SymbolRegistry.delete(this.node);
+  }
+};
+function createEffect(fn) {
+  const inst = new EffectInstance(fn);
+  inst.run();
+  return () => inst.dispose();
+}
+export {
+  batch,
+  computed,
+  createEffect,
+  onCleanup,
+  signal
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@signal-kernel/core",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.48.1",
+    "@typescript-eslint/parser": "^8.48.1",
+    "eslint": "^9.39.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --tsconfig tsconfig.dts.json",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}