@cplieger/reactive 1.0.7 → 1.1.0

package/README.md

@@ -5,9 +5,9 @@
 [![JSR](https://jsr.io/badges/@cplieger/reactive)](https://jsr.io/@cplieger/reactive)
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](LICENSE)
 
-> Signals + DOM-reconciliation micro-framework for TypeScript
+> Signals + collections + DOM-reconciliation micro-framework for TypeScript
 
-A standalone reactive primitives library providing fine-grained signals with automatic dependency tracking, synchronous batched effects, keyed-list DOM reconciliation, structural tree-diffing, and a typed per-key reactive store. Zero dependencies beyond the DOM API.
+A standalone reactive app-skeleton: fine-grained signals with automatic dependency tracking and synchronous batched effects, a typed per-key reactive store, a dynamic per-id signal registry (`SignalMap`), a reactive ordered keyed `Collection`, a two-tier list render binding (`bindList`), a CSP-safe element factory (`el`), keyed-list DOM reconciliation, structural tree-diffing, and a typed event bus (`createBus`). The store, `SignalMap`, and `Collection` are thin facades over the single signal engine — one reactive core, not several. The bus is the deliberate counterpart for discrete events (state lives in signals; events go on the bus). Zero dependencies beyond the DOM API.
 
 Mirrors semantics from @preact/signals-core and solid-js reactivity.
 
@@ -79,16 +79,42 @@ isComputed(doubled); // true
 - `isComputed(value): boolean` — type guard for computed signals
 - `setEffectErrorHandler(handler): EffectErrorHandler` — set global error handler for effects; returns the previous handler
 
-### DOM Reconciliation
+### DOM building & reconciliation
 
+- `el(tag, attrs?, ...children)` — CSP-safe element factory (the build half; `reconcile`/`patch` are the commit half). `className` → class; `on*` → handler property + `trackHandler` (so `patch` reconciles handlers); boolean DOM props (`hidden`/`disabled`/`checked`/`selected`/…) and `value`/`colSpan`/`rowSpan`/`tabIndex`/`htmlFor` → properties; everything else (`data-*`, `aria-*`, `style`, `id`) → `setAttribute`. String children become text nodes (never parsed as HTML); null/undefined attrs and children are skipped.
 - `reconcile<T>(parent, items, spec)` — keyed-list DOM reconciliation with mount/update/onRemove lifecycle
-- `patch(parent, ...children)` — structural tree-diff, replacing a parent's children with reconciled new nodes
+- `patch(parent, ...children)` — structural tree-diff, replacing a parent's children with reconciled new nodes. Element nodes are keyed by their first `data-col` or `*-id` attribute (so reorders/re-patches reuse the matched node); unkeyed nodes match by position.
 - `reconcileChildren(parent, newChildren)` — low-level child reconciliation against existing DOM
 - `trackHandler(el, key)` — register an `on*` property for handler reconciliation during tree-diff
 
 ### Store
 
-- `createStore<M>(): Store<M>` — typed per-key reactive store with `get`, `set`, `subscribe`, `effect`, `computed`, and `batch` methods
+`createStore` and `SignalMap` are thin facades over the one signal engine — there is no second reactivity implementation. `createStore` lazily backs each key with a signal; `SignalMap` is a registry of signals keyed by a runtime string id.
+
+- `createStore<M>(): Store<M>` — typed, fixed-key reactive store with `get`, `set`, `subscribe`, `effect`, `computed`, and `batch`. `subscribe` notifies on change only (not immediately on subscribe). A `computed` key whose fn reads its own output throws `Error("Cycle detected")` rather than looping.
+- `SignalMap<V>` — dynamic per-id signal registry: `get(id)`, `ensure(id, initial)`, `clear(id)`, `clearAll()`. For reactive state whose key set isn't known at the type level (per-message streaming text, per-row state, …); complements `createStore`'s fixed key set.
+
+### Collections
+
+A reactive ordered collection of keyed entities — the data half of the two-tier list pattern. A per-entity content update touches only that entity's subscribers; add/remove/reorder bumps the structure signal (`ids`). Built on `signal` + `SignalMap`.
+
+- `createCollection<T>(keyOf: (item: T) => string): Collection<T>` — returns a collection with:
+  - `setAll(items)` — replace everything (same-order replacement does not bump `ids`)
+  - `upsert(item)` — add/replace one (appends new ids); `prepend(items)` — add to the front (scroll-up/load-older pagination)
+  - `update(id, next | updater)` / `remove(id)` / `clear()`
+  - `get(id)` / `has(id)` (untracked), `signalFor(id)` (reactive per-entity), `size`
+  - `ids: ReadonlySignal<readonly string[]>` — structure tier (add/remove/reorder only)
+  - `items()` — ordered reactive snapshot (tracks order + every entity)
+
+### List rendering
+
+- `bindList<T>(parent, source, spec): () => void` — two-tier render binding. `source` is a `ListSource<T>` = `{ ids, signalFor }`; a `Collection` satisfies it directly, and a filtered/sorted/paginated view is just `{ ids: computed(...), signalFor: collection.signalFor }` (pagination = a sliced view, not a separate primitive). One structural effect tracks `source.ids` and `reconcile`s the row list; each row owns a private effect tracking only its own entity signal, so a per-entity change repaints just that row with no structural reconcile. `spec`: `{ mount(item, id) => HTMLElement; update?(el, item, id); onRemove?(el, id) }` (`update` runs at mount and on every later change). Returns a dispose that tears down the structural effect and every row effect.
+
+### Event bus
+
+State lives in signals; discrete events go on a bus. `createBus` is the typed event primitive (not reactive state — no retained value).
+
+- `createBus<EventMap>(options?): Bus<EventMap>` — `on`/`once`/`off`/`emit`/`clear`. Handlers are snapshot-cached (rebuilt only on mutation; a handler unsubscribed mid-emit still fires for that emit). Events whose payload type is `undefined` emit with no payload argument. A throwing handler is isolated via `options.onError` (default `console.error`).
 
 ## Correctness guarantees
 

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "exports": {
     ".": "./src/index.ts"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "type": "module",
   "sideEffects": false,
   "exports": {

package/src/bind-list.ts

@@ -0,0 +1,92 @@
+// bind-list.ts — two-tier render binding for a reactive list source.
+//
+// Tier 1 (structure): one effect tracks `source.ids` and runs `reconcile`
+// over the id list, so add/remove/reorder touch the DOM minimally.
+// Tier 2 (content): each row owns a private effect that tracks ONLY its own
+// entity signal, so a per-entity update repaints just that row without a
+// structural reconcile. The engine isolates nested-effect tracking
+// (evalContext save/restore in signal.ts), so the per-row effect's reads never
+// leak into the structural effect.
+//
+// The source is a `ListSource<T>` — anything exposing a structure signal
+// (`ids`) plus a per-id content signal lookup (`signalFor`). A `Collection<T>`
+// satisfies it directly; a filtered/sorted/paginated view is just a `computed`
+// id-list paired with the collection's `signalFor` (so pagination is a sliced
+// view, not a separate primitive).
+
+import { reconcile } from "./reconcile.js";
+import { effect, type ReadonlySignal } from "./signal.js";
+
+/** The minimal reactive surface `bindList` renders: a structure signal (the
+ *  ordered ids) and a per-id content-signal lookup. `Collection<T>` satisfies
+ *  this; so does `{ ids: computed(...), signalFor: collection.signalFor }`. */
+export interface ListSource<T> {
+  readonly ids: ReadonlySignal<readonly string[]>;
+  signalFor(id: string): ReadonlySignal<T> | undefined;
+}
+
+/** Row lifecycle for `bindList`. */
+export interface ListSpec<T> {
+  /** Create the row element for a new entity. Receives the entity's current
+   *  value and id. Keep this to structural shell creation; let `update` fill
+   *  reactive content (it runs once at mount and on every later change). */
+  mount: (item: T, id: string) => HTMLElement;
+  /** Update a row when its entity changes. Runs immediately at mount and again
+   *  on every per-entity change (the content tier). Omit for immutable rows
+   *  whose `mount` renders everything. */
+  update?: (el: HTMLElement, item: T, id: string) => void;
+  /** Optional cleanup when a row leaves the list (fires before the element is
+   *  removed from the DOM). */
+  onRemove?: (el: HTMLElement, id: string) => void;
+}
+
+/** Bind a list source to a parent node with two-tier reactivity. Returns a
+ *  dispose function that tears down the structural effect and every row
+ *  effect. */
+export function bindList<T>(
+  parent: ParentNode,
+  source: ListSource<T>,
+  spec: ListSpec<T>,
+): () => void {
+  const rowDisposers = new Map<string, () => void>();
+
+  const disposeStructural = effect(() => {
+    const ids = source.ids.value; // structure tier: re-runs on add/remove/reorder only
+    reconcile<string>(parent, ids, {
+      key: (id) => id,
+      mount: (id) => {
+        const sig = source.signalFor(id);
+        const el = spec.mount((sig === undefined ? undefined : sig.peek()) as T, id);
+        if (spec.update !== undefined) {
+          const update = spec.update;
+          // content tier: isolated per-row effect; runs now (fills content)
+          // and on every later change to THIS entity.
+          rowDisposers.set(
+            id,
+            effect(() => {
+              const cur = source.signalFor(id);
+              if (cur !== undefined) {
+                update(el, cur.value, id);
+              }
+            }),
+          );
+        }
+        return el;
+      },
+      // No structural `update`: content is owned entirely by the per-row effect.
+      onRemove: (el, id) => {
+        rowDisposers.get(id)?.();
+        rowDisposers.delete(id);
+        spec.onRemove?.(el, id);
+      },
+    });
+  });
+
+  return () => {
+    disposeStructural();
+    for (const dispose of rowDisposers.values()) {
+      dispose();
+    }
+    rowDisposers.clear();
+  };
+}

package/src/bus.ts

@@ -0,0 +1,133 @@
+// bus.ts — typed event bus (discrete events, NOT reactive state).
+//
+// The deliberate counterpart to signals. A signal models continuous STATE:
+// it has a current value you read and subscribe to. A bus models discrete
+// EVENTS: fire-and-forget notifications with no retained value. Reach for a
+// signal/Collection when "what is the current value?" makes sense; reach for
+// the bus when "X just happened" does (navigation, "refresh requested",
+// "escape pressed"). Mixing the two is the smell this split prevents.
+//
+// Handler sets are snapshot-cached: the iteration array is rebuilt only when
+// the set is mutated, not on every emit, and a handler unsubscribed during an
+// emit still fires for that emit (it was in the snapshot). No-payload events
+// use `undefined` as their payload type.
+
+/** Handler for a bus event. Events whose payload type is `undefined` take no
+ *  argument. */
+export type BusHandler<T> = T extends undefined ? () => void : (payload: T) => void;
+
+/** A typed event bus over an event→payload map `M`. Methods are arrow-function
+ *  properties (not method signatures) so consumers can safely destructure
+ *  `const { on, emit } = bus` without unbound-`this` warnings. */
+export interface Bus<M> {
+  /** Subscribe to an event. Returns an unsubscribe function. */
+  on: <K extends keyof M>(event: K, handler: BusHandler<M[K]>) => () => void;
+  /** Subscribe for exactly one emit, then auto-unsubscribe. Returns an
+   *  unsubscribe function (to cancel before it fires). */
+  once: <K extends keyof M>(event: K, handler: BusHandler<M[K]>) => () => void;
+  /** Remove a previously-registered handler (no-op if absent). */
+  off: <K extends keyof M>(event: K, handler: BusHandler<M[K]>) => void;
+  /** Emit an event. Events whose payload is `undefined` are emitted with no
+   *  payload argument. */
+  emit: <K extends keyof M>(
+    ...args: M[K] extends undefined ? [event: K] : [event: K, payload: M[K]]
+  ) => void;
+  /** Remove all handlers for one event, or all handlers entirely. */
+  clear: (event?: keyof M) => void;
+}
+
+type AnyHandler = (payload?: unknown) => void;
+
+interface Slot {
+  set: Set<AnyHandler>;
+  snapshot: AnyHandler[];
+  dirty: boolean;
+}
+
+/** Create a typed event bus. `onError` (default `console.error`) isolates a
+ *  throwing handler so it can't break sibling handlers or the emitter. */
+export function createBus<M>(options?: {
+  onError?: (event: keyof M, err: unknown) => void;
+}): Bus<M> {
+  const slots = new Map<keyof M, Slot>();
+  const onError =
+    options?.onError ??
+    ((event: keyof M, err: unknown): void => {
+      console.error(`[bus] handler error for "${String(event)}":`, err);
+    });
+
+  function slotFor(event: keyof M): Slot {
+    let slot = slots.get(event);
+    if (slot === undefined) {
+      slot = { set: new Set(), snapshot: [], dirty: false };
+      slots.set(event, slot);
+    }
+    return slot;
+  }
+
+  function on<K extends keyof M>(event: K, handler: BusHandler<M[K]>): () => void {
+    const slot = slotFor(event);
+    slot.set.add(handler as AnyHandler);
+    slot.dirty = true;
+    return (): void => {
+      off(event, handler);
+    };
+  }
+
+  function off<K extends keyof M>(event: K, handler: BusHandler<M[K]>): void {
+    const slot = slots.get(event);
+    if (slot === undefined) {
+      return;
+    }
+    if (slot.set.delete(handler as AnyHandler)) {
+      slot.dirty = true;
+    }
+  }
+
+  function once<K extends keyof M>(event: K, handler: BusHandler<M[K]>): () => void {
+    const wrapped = ((...callArgs: unknown[]): void => {
+      off(event, wrapped);
+      (handler as AnyHandler)(...callArgs);
+    }) as BusHandler<M[K]>;
+    return on(event, wrapped);
+  }
+
+  function emit<K extends keyof M>(
+    ...args: M[K] extends undefined ? [event: K] : [event: K, payload: M[K]]
+  ): void {
+    const [event, payload] = args as [K, unknown];
+    const slot = slots.get(event);
+    if (slot === undefined) {
+      return;
+    }
+    if (slot.dirty) {
+      slot.snapshot = Array.from(slot.set);
+      slot.dirty = false;
+    }
+    // No-payload events (`emit(event)` with no second arg) invoke handlers with
+    // zero arguments, honoring the `() => void` handler type — a `() => void`
+    // handler should never receive a stray `undefined`.
+    const hasPayload = args.length > 1;
+    for (const handler of slot.snapshot) {
+      try {
+        if (hasPayload) {
+          handler(payload);
+        } else {
+          handler();
+        }
+      } catch (err) {
+        onError(event, err);
+      }
+    }
+  }
+
+  function clear(event?: keyof M): void {
+    if (event === undefined) {
+      slots.clear();
+    } else {
+      slots.delete(event);
+    }
+  }
+
+  return { on, once, off, emit, clear };
+}

package/src/collection.ts

@@ -0,0 +1,173 @@
+// collection.ts — reactive ordered collection of keyed entities.
+//
+// Generalizes the "list of entities, each independently reactive, plus a
+// separate structure signal" model: a per-entity content update touches only
+// that entity's subscribers, while add/remove/reorder bumps the `ids` signal.
+// This is the data half of the two-tier list pattern (see `bindList` for the
+// render half). Built on `signal` + `SignalMap` — no separate engine.
+
+import { signal, batch, type ReadonlySignal } from "./signal.js";
+import { SignalMap } from "./signal-map.js";
+
+/** A reactive, ordered, keyed collection of entities of type T. */
+export interface Collection<T> {
+  /** Replace the whole collection (e.g. initial load). Entities no longer
+   *  present are dropped; the order becomes exactly `items`. */
+  setAll(items: readonly T[]): void;
+  /** Add a new entity or replace an existing one (keyed by `keyOf`). New
+   *  entities are appended to the order. */
+  upsert(item: T): void;
+  /** Add new entities to the FRONT of the order (e.g. loading older items for
+   *  scroll-up pagination). Existing ids are updated in place without moving. */
+  prepend(items: readonly T[]): void;
+  /** Update one entity in place (no-op if absent). Pass a value or an
+   *  updater. Does not change order. */
+  update(id: string, next: T | ((cur: T) => T)): void;
+  /** Remove one entity (no-op if absent). */
+  remove(id: string): void;
+  /** Remove every entity. */
+  clear(): void;
+  /** Current value of one entity (untracked peek), or undefined. */
+  get(id: string): T | undefined;
+  /** Whether an entity is present (untracked). */
+  has(id: string): boolean;
+  /** Reactive per-entity signal, or undefined if absent. Read inside an effect
+   *  to react only when THIS entity changes (the content tier). */
+  signalFor(id: string): ReadonlySignal<T> | undefined;
+  /** Reactive ordered id list — changes on add/remove/reorder, NOT on a
+   *  per-entity content update (the structure tier). */
+  readonly ids: ReadonlySignal<readonly string[]>;
+  /** Ordered snapshot of entity values. Reactive: reading this inside an
+   *  effect tracks order AND every entity (coarse — use `ids` + `signalFor`
+   *  for the two-tier split). */
+  items(): T[];
+  /** Entity count (untracked). */
+  readonly size: number;
+}
+
+/** Create a reactive ordered keyed collection. `keyOf` derives a stable
+ *  string id from an entity. */
+export function createCollection<T>(keyOf: (item: T) => string): Collection<T> {
+  // Shallow-equal so the structure tier fires only when the id sequence
+  // actually changes (a same-order setAll updates entities without a
+  // spurious structural re-render).
+  const order = signal<readonly string[]>([], {
+    equals: (a, b) => a.length === b.length && a.every((x, i) => x === b[i]),
+  });
+  const sigs = new SignalMap<T>();
+
+  function setAll(items: readonly T[]): void {
+    // Atomic: batch the per-entity writes + the order swap so effects (and any
+    // row update that cross-reads siblings) only run once the whole collection
+    // is consistent, not mid-mutation.
+    batch(() => {
+      const ids: string[] = [];
+      const seen = new Set<string>();
+      for (const item of items) {
+        const id = keyOf(item);
+        ids.push(id);
+        seen.add(id);
+        sigs.ensure(id, item).value = item;
+      }
+      for (const id of order.peek()) {
+        if (!seen.has(id)) {
+          sigs.clear(id);
+        }
+      }
+      order.value = ids;
+    });
+  }
+
+  function upsert(item: T): void {
+    const id = keyOf(item);
+    const existing = sigs.get(id);
+    if (existing === undefined) {
+      sigs.ensure(id, item);
+      order.value = [...order.peek(), id];
+    } else {
+      existing.value = item;
+    }
+  }
+
+  function prepend(items: readonly T[]): void {
+    batch(() => {
+      const newIds: string[] = [];
+      for (const item of items) {
+        const id = keyOf(item);
+        const existing = sigs.get(id);
+        if (existing === undefined) {
+          sigs.ensure(id, item);
+          newIds.push(id);
+        } else {
+          existing.value = item;
+        }
+      }
+      if (newIds.length > 0) {
+        order.value = [...newIds, ...order.peek()];
+      }
+    });
+  }
+
+  function update(id: string, next: T | ((cur: T) => T)): void {
+    const s = sigs.get(id);
+    if (s === undefined) {
+      return;
+    }
+    s.value = typeof next === "function" ? (next as (cur: T) => T)(s.peek()) : next;
+  }
+
+  function remove(id: string): void {
+    if (sigs.get(id) === undefined) {
+      return;
+    }
+    sigs.clear(id);
+    order.value = order.peek().filter((x) => x !== id);
+  }
+
+  function clear(): void {
+    sigs.clearAll();
+    order.value = [];
+  }
+
+  function get(id: string): T | undefined {
+    return sigs.get(id)?.peek();
+  }
+
+  function has(id: string): boolean {
+    return sigs.get(id) !== undefined;
+  }
+
+  function signalFor(id: string): ReadonlySignal<T> | undefined {
+    return sigs.get(id);
+  }
+
+  function items(): T[] {
+    const result: T[] = [];
+    for (const id of order.value) {
+      const s = sigs.get(id);
+      if (s !== undefined) {
+        result.push(s.value);
+      }
+    }
+    return result;
+  }
+
+  return {
+    setAll,
+    upsert,
+    prepend,
+    update,
+    remove,
+    clear,
+    get,
+    has,
+    signalFor,
+    items,
+    get ids(): ReadonlySignal<readonly string[]> {
+      return order;
+    },
+    get size(): number {
+      return order.peek().length;
+    },
+  };
+}

package/src/el.ts

@@ -0,0 +1,73 @@
+// el.ts — CSP-safe DOM element factory. The build half of the DOM layer; pairs
+// with reconcile/patch (the commit half). `on*` handlers are assigned as
+// properties AND registered via trackHandler, so patch() reconciles them across
+// re-renders. No innerHTML, no string templating — safe under a strict CSP.
+
+import { trackHandler } from "./reconcile-tree.js";
+
+/** A value for an element attribute/property/handler. Functions are treated as
+ *  event handlers when the key starts with `on`. */
+export type AttrValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | ((...args: never[]) => unknown);
+
+// Keys set as DOM *properties* (not attributes) because the attribute form
+// either doesn't reflect (value/checked) or is awkward (boolean presence).
+const BOOL_PROPS = new Set([
+  "hidden",
+  "disabled",
+  "checked",
+  "selected",
+  "multiple",
+  "readOnly",
+  "required",
+  "open",
+  "default",
+]);
+const VALUE_PROPS = new Set(["value", "colSpan", "rowSpan", "tabIndex", "htmlFor"]);
+
+/** Create an element: `el("button", { className: "x", onclick: fn }, "Label")`.
+ *  - `className` → the class property
+ *  - `on*` → handler property + `trackHandler` (reconciled by patch)
+ *  - boolean DOM props (hidden/disabled/checked/selected/…) → property
+ *  - value/colSpan/rowSpan/tabIndex/htmlFor → property
+ *  - everything else → `setAttribute` (incl. `data-*`, `aria-*`, `style`, `id`)
+ *  Null/undefined attrs and children are skipped. String children become text
+ *  nodes (never parsed as HTML). */
+export function el(
+  tag: string,
+  attrs?: Record<string, AttrValue> | null,
+  ...children: (string | Node | null | undefined)[]
+): HTMLElement {
+  const e = document.createElement(tag);
+  if (attrs) {
+    for (const [k, v] of Object.entries(attrs)) {
+      if (v === null || v === undefined) {
+        continue;
+      }
+      if (k === "className") {
+        e.className = v as string;
+      } else if (k.startsWith("on")) {
+        (e as unknown as Record<string, unknown>)[k] = v;
+        trackHandler(e, k);
+      } else if (BOOL_PROPS.has(k)) {
+        (e as unknown as Record<string, unknown>)[k] = v;
+      } else if (VALUE_PROPS.has(k)) {
+        (e as unknown as Record<string, unknown>)[k] = v;
+      } else {
+        e.setAttribute(k, String(v));
+      }
+    }
+  }
+  for (const child of children) {
+    if (child === null || child === undefined) {
+      continue;
+    }
+    e.appendChild(typeof child === "string" ? document.createTextNode(child) : child);
+  }
+  return e;
+}

package/src/index.ts

@@ -20,6 +20,15 @@ export type {
 } from "./signal.js";
 export { createStore } from "./store.js";
 export type { Store } from "./store.js";
+export { SignalMap } from "./signal-map.js";
+export { createCollection } from "./collection.js";
+export type { Collection } from "./collection.js";
+export { bindList } from "./bind-list.js";
+export type { ListSpec, ListSource } from "./bind-list.js";
+export { createBus } from "./bus.js";
+export type { Bus, BusHandler } from "./bus.js";
+export { el } from "./el.js";
+export type { AttrValue } from "./el.js";
 export { reconcile, KEY_ATTR } from "./reconcile.js";
 export type { ReconcileSpec } from "./reconcile.js";
 export { patch, reconcileChildren, trackHandler } from "./reconcile-tree.js";

package/src/reconcile-tree.ts

@@ -124,7 +124,7 @@ function nodeKey(node: Node): string {
     return "";
   }
   for (const attr of (node as Element).attributes) {
-    if (attr.name.endsWith("-id")) {
+    if (attr.name === "data-col" || attr.name.endsWith("-id")) {
       return `${attr.name}=${attr.value}`;
     }
   }

package/src/signal-map.ts

@@ -0,0 +1,39 @@
+// SignalMap — a registry of lazily-created signals keyed by string ID.
+//
+// For dynamic, per-entity reactive state where the key set isn't known ahead
+// of time (per-message streaming text, per-tool-call, per-row state, …). This
+// complements `createStore`, whose typed key set is fixed at the type level.
+// Like everything else here it's a facade over `signal` — no separate engine.
+
+import { signal, type Signal } from "./signal.js";
+
+/** A typed map of lazily-created signals keyed by string ID. Provides
+ *  get / ensure / clear / clearAll over any value type. */
+export class SignalMap<V> {
+  private readonly map = new Map<string, Signal<V>>();
+
+  /** The signal for `id`, or undefined if none has been created yet. */
+  get(id: string): Signal<V> | undefined {
+    return this.map.get(id);
+  }
+
+  /** The signal for `id`, creating it with `initial` on first access. */
+  ensure(id: string, initial: V): Signal<V> {
+    let sig = this.map.get(id);
+    if (sig === undefined) {
+      sig = signal(initial);
+      this.map.set(id, sig);
+    }
+    return sig;
+  }
+
+  /** Drop the signal for `id` (e.g. when the entity is removed). */
+  clear(id: string): void {
+    this.map.delete(id);
+  }
+
+  /** Drop every signal — e.g. on a wholesale context switch. */
+  clearAll(): void {
+    this.map.clear();
+  }
+}

package/src/store.ts

@@ -1,13 +1,17 @@
-// Typed per-key reactive store with auto-tracked effects, computed, and batching.
+// Typed per-key reactive store — a thin facade over the signal engine.
+//
+// Each key is backed by a lazily-created signal, so the store inherits the
+// engine's glitch-freedom, cycle detection, batching, and error handling.
+// There is NO separate reactivity implementation here: get/set read and
+// write signals, effect/batch are the engine's own, and auto-tracking falls
+// out of reading `signal.value` inside an effect.
 //
 // Usage:
 //   import { createStore } from './store.js';
 //   interface MyMap { count: number; name: string }
 //   const { get, set, subscribe, effect, computed, batch } = createStore<MyMap>();
 
-type Callback = (value: unknown) => void;
-// eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- void is intentional for effect return
-type Cleanup = void | (() => void);
+import { signal, effect, batch, type Signal, type Cleanup } from "./signal.js";
 
 /** A typed per-key reactive store with auto-tracked effects, computed, and batching. */
 export interface Store<M> {
@@ -19,141 +23,51 @@ export interface Store<M> {
   batch(fn: () => void): void;
 }
 
-/** Create a typed reactive store. Keys are auto-tracked in effects; writes notify subscribers. */
+/** Create a typed reactive store. Keys are lazily backed by signals; reading a
+ *  key inside an effect auto-tracks it, and writes notify through the engine. */
 export function createStore<M>(): Store<M> {
-  const state: Record<string, unknown> = {};
-  const subscribers: Record<string, Callback[]> = {};
-
-  let tracking: Set<string> | null = null;
-  let batchDepth = 0;
-  let pendingKeys: Map<string, unknown> | null = null;
+  const sigs = new Map<string, Signal<unknown>>();
 
-  function notifySubs(key: string, value: unknown): void {
-    const cbs = subscribers[key];
-    if (!cbs) {
-      return;
-    }
-    for (const cb of cbs) {
-      try {
-        cb(value);
-      } catch (e) {
-        console.error("store subscriber error:", e);
-      }
+  function sigFor<K extends keyof M & string>(key: K): Signal<M[K]> {
+    let s = sigs.get(key);
+    if (s === undefined) {
+      // Unset keys read as `undefined` (matching a sparse record) until first set.
+      s = signal<unknown>(undefined);
+      sigs.set(key, s);
     }
+    return s as Signal<M[K]>;
   }
 
   function get<K extends keyof M & string>(key: K): M[K] {
-    if (tracking) {
-      tracking.add(key);
-    }
-    return state[key] as M[K];
+    return sigFor(key).value;
   }
 
   function set<K extends keyof M & string>(key: K, value: M[K]): void {
-    const prev = state[key];
-    state[key] = value;
-    if (Object.is(prev, value)) {
-      return;
-    }
-    if (batchDepth > 0) {
-      pendingKeys ??= new Map();
-      pendingKeys.set(key, value);
-    } else {
-      notifySubs(key, value);
-    }
+    sigFor(key).value = value;
   }
 
+  // Notify on change only (not immediately on subscribe) — the engine's
+  // `subscribe` fires immediately, so skip the initial effect run.
   function subscribe<K extends keyof M & string>(key: K, cb: (value: M[K]) => void): () => void {
-    subscribers[key] ??= [];
-    subscribers[key].push(cb as Callback);
-    return () => {
-      const arr = subscribers[key];
-      if (arr) {
-        subscribers[key] = arr.filter((c) => c !== cb);
-      }
-    };
-  }
-
-  function storeBatch(fn: () => void): void {
-    batchDepth++;
-    try {
-      fn();
-    } finally {
-      batchDepth--;
-      if (batchDepth === 0 && pendingKeys) {
-        const p = pendingKeys;
-        pendingKeys = null;
-        for (const [k, v] of p) {
-          notifySubs(k, v);
-        }
-      }
-    }
-  }
-
-  function storeEffect(fn: () => Cleanup): () => void {
-    let unsubs: (() => void)[] = [];
-    let cleanup: Cleanup;
-    let disposed = false;
-
-    const run = (): void => {
-      if (disposed) {
-        return;
-      }
-      for (const u of unsubs) {
-        u();
-      }
-      unsubs = [];
-      if (cleanup) {
-        const c = cleanup;
-        cleanup = undefined;
-        try {
-          c();
-        } catch (e) {
-          console.error("store effect cleanup error:", e);
-        }
-      }
-      const prev = tracking;
-      tracking = new Set();
-      try {
-        cleanup = fn();
-      } catch (e) {
-        console.error("store effect error:", e);
-      }
-      const deps = tracking;
-      tracking = prev;
-      for (const dep of deps) {
-        unsubs.push(
-          subscribe(dep as keyof M & string, run as (value: M[keyof M & string]) => void),
-        );
-      }
-    };
-    run();
-    return () => {
-      if (disposed) {
+    const s = sigFor(key);
+    let primed = false;
+    return effect(() => {
+      const v = s.value;
+      if (!primed) {
+        primed = true;
         return;
       }
-      disposed = true;
-      for (const u of unsubs) {
-        u();
-      }
-      unsubs = [];
-      if (cleanup) {
-        const c = cleanup;
-        cleanup = undefined;
-        try {
-          c();
-        } catch (e) {
-          console.error("store effect cleanup error:", e);
-        }
-      }
-    };
+      cb(v);
+    });
   }
 
+  // A derived key: an effect that writes `outputKey` from `fn`. If `fn` reads
+  // `outputKey` the engine throws "Cycle detected" rather than looping.
   function computed<K extends keyof M & string>(outputKey: K, fn: () => M[K]): () => void {
-    return storeEffect(() => {
+    return effect(() => {
       set(outputKey, fn());
     });
   }
 
-  return { get, set, subscribe, effect: storeEffect, computed, batch: storeBatch };
+  return { get, set, subscribe, effect, computed, batch };
 }