@matthesketh/utopia-core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Hesketh
+
+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,62 @@
+# @matthesketh/utopia-core
+
+Fine-grained signals reactivity system for UtopiaJS.
+
+## Install
+
+```bash
+pnpm add @matthesketh/utopia-core
+```
+
+## Usage
+
+```ts
+import { signal, computed, effect, batch, untrack } from '@matthesketh/utopia-core';
+
+// Writable signal
+const count = signal(0);
+count();          // read (tracked)
+count.value;      // read (tracked)
+count.peek();     // read (untracked)
+count.set(1);     // write
+count.update(n => n + 1); // write via callback
+
+// Lazy computed
+const double = computed(() => count() * 2);
+double();         // 4
+
+// Reactive effect
+const dispose = effect(() => {
+  console.log('count is', count());
+  return () => console.log('cleaning up');
+});
+dispose(); // stop watching
+
+// Batch multiple writes
+batch(() => {
+  count.set(10);
+  count.set(20);
+}); // effects run once after batch
+
+// Untracked reads
+effect(() => {
+  const tracked = count();
+  const untracked_val = untrack(() => count());
+});
+```
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `signal(value)` | Writable reactive cell. Read via `()` or `.value`, write via `.set()` or `.update()`. |
+| `computed(fn)` | Lazy derived value. Recomputes only when dependencies change and the value is read. |
+| `effect(fn)` | Eager side-effect. Re-runs when dependencies change. Returns a dispose function. |
+| `batch(fn)` | Groups multiple writes -- effects only run once after the batch completes. |
+| `untrack(fn)` | Reads signals inside `fn` without creating dependency subscriptions. |
+
+See [docs/architecture.md](../../docs/architecture.md) for full details on the reactivity system.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,283 @@
+"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,
+  effect: () => effect,
+  signal: () => signal,
+  untrack: () => untrack
+});
+module.exports = __toCommonJS(index_exports);
+var subscriberStack = [];
+var currentSubscriber = null;
+var batchDepth = 0;
+var pendingEffects = /* @__PURE__ */ new Set();
+function pushSubscriber(sub) {
+  subscriberStack.push(currentSubscriber);
+  currentSubscriber = sub;
+}
+function popSubscriber() {
+  currentSubscriber = subscriberStack.pop() ?? null;
+}
+var SignalNode = class {
+  /** Current stored value. */
+  _value;
+  /** Set of subscribers currently tracking this signal. */
+  _subscribers = /* @__PURE__ */ new Set();
+  constructor(value) {
+    this._value = value;
+  }
+  /** Read value, registering the current subscriber if any. */
+  _read() {
+    if (currentSubscriber !== null) {
+      this._subscribers.add(currentSubscriber);
+      currentSubscriber.dependencies.add(this);
+    }
+    return this._value;
+  }
+  /** Read value WITHOUT tracking. */
+  _peek() {
+    return this._value;
+  }
+  /** Write a new value. If changed, notify all subscribers. */
+  _write(newValue) {
+    if (Object.is(this._value, newValue)) {
+      return;
+    }
+    this._value = newValue;
+    batchDepth++;
+    try {
+      const subs = Array.from(this._subscribers);
+      for (let i = 0; i < subs.length; i++) {
+        subs[i].notify();
+      }
+    } finally {
+      batchDepth--;
+      if (batchDepth === 0) {
+        flushPendingEffects();
+      }
+    }
+  }
+};
+function signal(initialValue) {
+  const node = new SignalNode(initialValue);
+  const read = (() => node._read());
+  Object.defineProperty(read, "value", {
+    get() {
+      return node._read();
+    },
+    enumerable: true,
+    configurable: false
+  });
+  read.peek = () => node._peek();
+  read.set = (newValue) => {
+    node._write(newValue);
+  };
+  read.update = (fn) => {
+    node._write(fn(node._value));
+  };
+  return read;
+}
+var ComputedNode = class {
+  _fn;
+  _value;
+  _dirty = true;
+  _initialized = false;
+  _signalNode;
+  dependencies = /* @__PURE__ */ new Set();
+  /**
+   * Whether we are currently recomputing. Used to prevent infinite loops
+   * and to correctly propagate to downstream subscribers only after our
+   * own value has settled.
+   */
+  _computing = false;
+  constructor(fn) {
+    this._fn = fn;
+    this._signalNode = new SignalNode(void 0);
+  }
+  /** Subscriber interface — called when an upstream dependency changes. */
+  notify() {
+    if (!this._dirty) {
+      this._dirty = true;
+      const subs = Array.from(this._signalNode._subscribers);
+      for (let i = 0; i < subs.length; i++) {
+        subs[i].notify();
+      }
+    }
+  }
+  /** Recompute (if dirty) and return the value. */
+  _read() {
+    if (this._dirty && !this._computing) {
+      this._recompute();
+    }
+    return this._signalNode._read();
+  }
+  /** Read without tracking. */
+  _peek() {
+    if (this._dirty && !this._computing) {
+      this._recompute();
+    }
+    return this._signalNode._peek();
+  }
+  /** Unsubscribe from all current dependencies. */
+  _cleanup() {
+    for (const dep of this.dependencies) {
+      dep._subscribers.delete(this);
+    }
+    this.dependencies.clear();
+  }
+  /** Recompute the derived value. */
+  _recompute() {
+    this._computing = true;
+    this._cleanup();
+    pushSubscriber(this);
+    try {
+      const newValue = this._fn();
+      this._dirty = false;
+      this._computing = false;
+      if (!this._initialized || !Object.is(newValue, this._signalNode._value)) {
+        this._initialized = true;
+        this._signalNode._value = newValue;
+      }
+    } finally {
+      popSubscriber();
+      this._computing = false;
+    }
+  }
+};
+function computed(fn) {
+  const node = new ComputedNode(fn);
+  const read = (() => node._read());
+  Object.defineProperty(read, "value", {
+    get() {
+      return node._read();
+    },
+    enumerable: true,
+    configurable: false
+  });
+  read.peek = () => node._peek();
+  return read;
+}
+var EffectNode = class {
+  _fn;
+  _cleanupFn = void 0;
+  _disposed = false;
+  dependencies = /* @__PURE__ */ new Set();
+  /**
+   * Flag to prevent re-entrant notification. When an effect is already
+   * queued (or currently executing), additional notifications are ignored.
+   */
+  _queued = false;
+  constructor(fn) {
+    this._fn = fn;
+  }
+  /** Subscriber interface — called when an upstream dependency changes. */
+  notify() {
+    if (this._disposed || this._queued) {
+      return;
+    }
+    this._queued = true;
+    if (batchDepth > 0) {
+      pendingEffects.add(this);
+    } else {
+      this._run();
+    }
+  }
+  /** Execute the effect, cleaning up previous subscriptions first. */
+  _run() {
+    if (this._disposed) {
+      this._queued = false;
+      return;
+    }
+    if (this._cleanupFn) {
+      this._cleanupFn();
+      this._cleanupFn = void 0;
+    }
+    this._unsubscribe();
+    pushSubscriber(this);
+    try {
+      const result = this._fn();
+      this._cleanupFn = typeof result === "function" ? result : void 0;
+    } finally {
+      popSubscriber();
+      this._queued = false;
+    }
+  }
+  /** Unsubscribe from all tracked dependencies. */
+  _unsubscribe() {
+    for (const dep of this.dependencies) {
+      dep._subscribers.delete(this);
+    }
+    this.dependencies.clear();
+  }
+  /** Dispose the effect permanently — runs cleanup and unsubscribes. */
+  _dispose() {
+    this._disposed = true;
+    if (this._cleanupFn) {
+      this._cleanupFn();
+      this._cleanupFn = void 0;
+    }
+    this._unsubscribe();
+    pendingEffects.delete(this);
+  }
+};
+function effect(fn) {
+  const node = new EffectNode(fn);
+  node._run();
+  return () => node._dispose();
+}
+function batch(fn) {
+  batchDepth++;
+  try {
+    return fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) {
+      flushPendingEffects();
+    }
+  }
+}
+function flushPendingEffects() {
+  while (pendingEffects.size > 0) {
+    const effects = Array.from(pendingEffects);
+    pendingEffects.clear();
+    for (let i = 0; i < effects.length; i++) {
+      effects[i]._run();
+    }
+  }
+}
+function untrack(fn) {
+  pushSubscriber(null);
+  try {
+    return fn();
+  } finally {
+    popSubscriber();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  batch,
+  computed,
+  effect,
+  signal,
+  untrack
+});

package/dist/index.d.cts

@@ -0,0 +1,83 @@
+/** A read-only reactive signal. */
+interface ReadonlySignal<T> {
+    /** Read the current value (tracks dependency). */
+    (): T;
+    /** Read the current value (tracks dependency). */
+    readonly value: T;
+    /** Read the current value WITHOUT tracking dependency. */
+    peek(): T;
+}
+/** A writable reactive signal. */
+interface Signal<T> extends ReadonlySignal<T> {
+    /** Set a new value. */
+    set(newValue: T): void;
+    /** Update via callback: fn(currentValue) => newValue. */
+    update(fn: (current: T) => T): void;
+}
+/**
+ * Creates a writable reactive signal.
+ *
+ * ```ts
+ * const count = signal(0);
+ * count()        // read (tracked)
+ * count.value    // read (tracked)
+ * count.peek()   // read (untracked)
+ * count.set(1)   // write
+ * count.update(n => n + 1) // write via callback
+ * ```
+ */
+declare function signal<T>(initialValue: T): Signal<T>;
+/**
+ * Creates a lazy computed (derived) signal.
+ *
+ * ```ts
+ * const double = computed(() => count() * 2);
+ * double()     // read (tracked)
+ * double.value // read (tracked)
+ * ```
+ */
+declare function computed<T>(fn: () => T): ReadonlySignal<T>;
+/**
+ * Creates a reactive side-effect that re-runs when its dependencies change.
+ *
+ * The callback may optionally return a cleanup function that is invoked
+ * before each re-execution and on disposal (like React useEffect).
+ *
+ * Returns a dispose function to stop the effect.
+ *
+ * ```ts
+ * const dispose = effect(() => {
+ *   console.log('count is', count());
+ *   return () => console.log('cleaning up');
+ * });
+ *
+ * dispose(); // stop watching
+ * ```
+ */
+declare function effect(fn: () => void | (() => void)): () => void;
+/**
+ * Batches multiple signal writes so that effects only run once after the
+ * batch completes.
+ *
+ * ```ts
+ * batch(() => {
+ *   a.set(1);
+ *   b.set(2);
+ * });
+ * // effects that depend on a AND b only run once
+ * ```
+ */
+declare function batch<T>(fn: () => T): T;
+/**
+ * Runs a function without tracking any signal reads as dependencies.
+ *
+ * ```ts
+ * effect(() => {
+ *   const x = a();                     // tracked
+ *   const y = untrack(() => b());      // NOT tracked
+ * });
+ * ```
+ */
+declare function untrack<T>(fn: () => T): T;
+
+export { type ReadonlySignal, type Signal, batch, computed, effect, signal, untrack };

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+/** A read-only reactive signal. */
+interface ReadonlySignal<T> {
+    /** Read the current value (tracks dependency). */
+    (): T;
+    /** Read the current value (tracks dependency). */
+    readonly value: T;
+    /** Read the current value WITHOUT tracking dependency. */
+    peek(): T;
+}
+/** A writable reactive signal. */
+interface Signal<T> extends ReadonlySignal<T> {
+    /** Set a new value. */
+    set(newValue: T): void;
+    /** Update via callback: fn(currentValue) => newValue. */
+    update(fn: (current: T) => T): void;
+}
+/**
+ * Creates a writable reactive signal.
+ *
+ * ```ts
+ * const count = signal(0);
+ * count()        // read (tracked)
+ * count.value    // read (tracked)
+ * count.peek()   // read (untracked)
+ * count.set(1)   // write
+ * count.update(n => n + 1) // write via callback
+ * ```
+ */
+declare function signal<T>(initialValue: T): Signal<T>;
+/**
+ * Creates a lazy computed (derived) signal.
+ *
+ * ```ts
+ * const double = computed(() => count() * 2);
+ * double()     // read (tracked)
+ * double.value // read (tracked)
+ * ```
+ */
+declare function computed<T>(fn: () => T): ReadonlySignal<T>;
+/**
+ * Creates a reactive side-effect that re-runs when its dependencies change.
+ *
+ * The callback may optionally return a cleanup function that is invoked
+ * before each re-execution and on disposal (like React useEffect).
+ *
+ * Returns a dispose function to stop the effect.
+ *
+ * ```ts
+ * const dispose = effect(() => {
+ *   console.log('count is', count());
+ *   return () => console.log('cleaning up');
+ * });
+ *
+ * dispose(); // stop watching
+ * ```
+ */
+declare function effect(fn: () => void | (() => void)): () => void;
+/**
+ * Batches multiple signal writes so that effects only run once after the
+ * batch completes.
+ *
+ * ```ts
+ * batch(() => {
+ *   a.set(1);
+ *   b.set(2);
+ * });
+ * // effects that depend on a AND b only run once
+ * ```
+ */
+declare function batch<T>(fn: () => T): T;
+/**
+ * Runs a function without tracking any signal reads as dependencies.
+ *
+ * ```ts
+ * effect(() => {
+ *   const x = a();                     // tracked
+ *   const y = untrack(() => b());      // NOT tracked
+ * });
+ * ```
+ */
+declare function untrack<T>(fn: () => T): T;
+
+export { type ReadonlySignal, type Signal, batch, computed, effect, signal, untrack };

package/dist/index.js

@@ -0,0 +1,254 @@
+// src/index.ts
+var subscriberStack = [];
+var currentSubscriber = null;
+var batchDepth = 0;
+var pendingEffects = /* @__PURE__ */ new Set();
+function pushSubscriber(sub) {
+  subscriberStack.push(currentSubscriber);
+  currentSubscriber = sub;
+}
+function popSubscriber() {
+  currentSubscriber = subscriberStack.pop() ?? null;
+}
+var SignalNode = class {
+  /** Current stored value. */
+  _value;
+  /** Set of subscribers currently tracking this signal. */
+  _subscribers = /* @__PURE__ */ new Set();
+  constructor(value) {
+    this._value = value;
+  }
+  /** Read value, registering the current subscriber if any. */
+  _read() {
+    if (currentSubscriber !== null) {
+      this._subscribers.add(currentSubscriber);
+      currentSubscriber.dependencies.add(this);
+    }
+    return this._value;
+  }
+  /** Read value WITHOUT tracking. */
+  _peek() {
+    return this._value;
+  }
+  /** Write a new value. If changed, notify all subscribers. */
+  _write(newValue) {
+    if (Object.is(this._value, newValue)) {
+      return;
+    }
+    this._value = newValue;
+    batchDepth++;
+    try {
+      const subs = Array.from(this._subscribers);
+      for (let i = 0; i < subs.length; i++) {
+        subs[i].notify();
+      }
+    } finally {
+      batchDepth--;
+      if (batchDepth === 0) {
+        flushPendingEffects();
+      }
+    }
+  }
+};
+function signal(initialValue) {
+  const node = new SignalNode(initialValue);
+  const read = (() => node._read());
+  Object.defineProperty(read, "value", {
+    get() {
+      return node._read();
+    },
+    enumerable: true,
+    configurable: false
+  });
+  read.peek = () => node._peek();
+  read.set = (newValue) => {
+    node._write(newValue);
+  };
+  read.update = (fn) => {
+    node._write(fn(node._value));
+  };
+  return read;
+}
+var ComputedNode = class {
+  _fn;
+  _value;
+  _dirty = true;
+  _initialized = false;
+  _signalNode;
+  dependencies = /* @__PURE__ */ new Set();
+  /**
+   * Whether we are currently recomputing. Used to prevent infinite loops
+   * and to correctly propagate to downstream subscribers only after our
+   * own value has settled.
+   */
+  _computing = false;
+  constructor(fn) {
+    this._fn = fn;
+    this._signalNode = new SignalNode(void 0);
+  }
+  /** Subscriber interface — called when an upstream dependency changes. */
+  notify() {
+    if (!this._dirty) {
+      this._dirty = true;
+      const subs = Array.from(this._signalNode._subscribers);
+      for (let i = 0; i < subs.length; i++) {
+        subs[i].notify();
+      }
+    }
+  }
+  /** Recompute (if dirty) and return the value. */
+  _read() {
+    if (this._dirty && !this._computing) {
+      this._recompute();
+    }
+    return this._signalNode._read();
+  }
+  /** Read without tracking. */
+  _peek() {
+    if (this._dirty && !this._computing) {
+      this._recompute();
+    }
+    return this._signalNode._peek();
+  }
+  /** Unsubscribe from all current dependencies. */
+  _cleanup() {
+    for (const dep of this.dependencies) {
+      dep._subscribers.delete(this);
+    }
+    this.dependencies.clear();
+  }
+  /** Recompute the derived value. */
+  _recompute() {
+    this._computing = true;
+    this._cleanup();
+    pushSubscriber(this);
+    try {
+      const newValue = this._fn();
+      this._dirty = false;
+      this._computing = false;
+      if (!this._initialized || !Object.is(newValue, this._signalNode._value)) {
+        this._initialized = true;
+        this._signalNode._value = newValue;
+      }
+    } finally {
+      popSubscriber();
+      this._computing = false;
+    }
+  }
+};
+function computed(fn) {
+  const node = new ComputedNode(fn);
+  const read = (() => node._read());
+  Object.defineProperty(read, "value", {
+    get() {
+      return node._read();
+    },
+    enumerable: true,
+    configurable: false
+  });
+  read.peek = () => node._peek();
+  return read;
+}
+var EffectNode = class {
+  _fn;
+  _cleanupFn = void 0;
+  _disposed = false;
+  dependencies = /* @__PURE__ */ new Set();
+  /**
+   * Flag to prevent re-entrant notification. When an effect is already
+   * queued (or currently executing), additional notifications are ignored.
+   */
+  _queued = false;
+  constructor(fn) {
+    this._fn = fn;
+  }
+  /** Subscriber interface — called when an upstream dependency changes. */
+  notify() {
+    if (this._disposed || this._queued) {
+      return;
+    }
+    this._queued = true;
+    if (batchDepth > 0) {
+      pendingEffects.add(this);
+    } else {
+      this._run();
+    }
+  }
+  /** Execute the effect, cleaning up previous subscriptions first. */
+  _run() {
+    if (this._disposed) {
+      this._queued = false;
+      return;
+    }
+    if (this._cleanupFn) {
+      this._cleanupFn();
+      this._cleanupFn = void 0;
+    }
+    this._unsubscribe();
+    pushSubscriber(this);
+    try {
+      const result = this._fn();
+      this._cleanupFn = typeof result === "function" ? result : void 0;
+    } finally {
+      popSubscriber();
+      this._queued = false;
+    }
+  }
+  /** Unsubscribe from all tracked dependencies. */
+  _unsubscribe() {
+    for (const dep of this.dependencies) {
+      dep._subscribers.delete(this);
+    }
+    this.dependencies.clear();
+  }
+  /** Dispose the effect permanently — runs cleanup and unsubscribes. */
+  _dispose() {
+    this._disposed = true;
+    if (this._cleanupFn) {
+      this._cleanupFn();
+      this._cleanupFn = void 0;
+    }
+    this._unsubscribe();
+    pendingEffects.delete(this);
+  }
+};
+function effect(fn) {
+  const node = new EffectNode(fn);
+  node._run();
+  return () => node._dispose();
+}
+function batch(fn) {
+  batchDepth++;
+  try {
+    return fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) {
+      flushPendingEffects();
+    }
+  }
+}
+function flushPendingEffects() {
+  while (pendingEffects.size > 0) {
+    const effects = Array.from(pendingEffects);
+    pendingEffects.clear();
+    for (let i = 0; i < effects.length; i++) {
+      effects[i]._run();
+    }
+  }
+}
+function untrack(fn) {
+  pushSubscriber(null);
+  try {
+    return fn();
+  } finally {
+    popSubscriber();
+  }
+}
+export {
+  batch,
+  computed,
+  effect,
+  signal,
+  untrack
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@matthesketh/utopia-core",
+  "version": "0.0.1",
+  "description": "Fine-grained signals reactivity system for UtopiaJS",
+  "type": "module",
+  "license": "MIT",
+  "author": "Matt <matt@matthesketh.pro>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wrxck/utopiajs.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/wrxck/utopiajs/tree/main/packages/core",
+  "keywords": [
+    "signals",
+    "reactive",
+    "fine-grained",
+    "state-management",
+    "utopiajs"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "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"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch"
+  }
+}