@zeix/cause-effect 0.18.0 → 0.18.1

package/.ai-context.md

@@ -28,8 +28,8 @@ Scope         — owner-only (createScope)
 ### Signal Types
 - **State** (`createState`): Mutable signals for primitive values and objects
 - **Sensor** (`createSensor`): Read-only signals for external input streams with automatic state updates. Use `SKIP_EQUALITY` for mutable object observation.
-- **Memo** (`createMemo`): Synchronous derived computations with memoization and reducer capabilities
-- **Task** (`createTask`): Async derived computations with automatic abort/cancellation
+- **Memo** (`createMemo`): Synchronous derived computations with memoization, reducer capabilities, and optional `watched(invalidate)` for external invalidation
+- **Task** (`createTask`): Async derived computations with automatic abort/cancellation and optional `watched(invalidate)` for external invalidation
 - **Store** (`createStore`): Mutable object signals with individually reactive properties via Proxy
 - **List** (`createList`): Mutable array signals with stable keys and reactive items
 - **Collection** (`createCollection`): Reactive collections — either externally-driven with watched lifecycle, or derived from List/Collection with item-level memoization
@@ -223,7 +223,7 @@ const processed = items.deriveCollection(item => item.toUpperCase())
 
 ## Resource Management
 
-**Sensor and Collection** use a start callback that returns a Cleanup function:
+**Sensor and Collection** use a watched callback that returns a Cleanup function:
 ```typescript
 const sensor = createSensor<T>((set) => {
   // setup input tracking, call set(value) to update
@@ -236,6 +236,17 @@ const feed = createCollection<T>((applyChanges) => {
 }, { keyConfig: item => item.id })
 ```
 
+**Memo and Task** use an optional `watched` callback in options that receives an `invalidate` function:
+```typescript
+const derived = createMemo(() => element.get().textContent ?? '', {
+  watched: (invalidate) => {
+    const obs = new MutationObserver(() => invalidate())
+    obs.observe(element.get(), { childList: true })
+    return () => obs.disconnect()
+  }
+})
+```
+
 **Store and List** use an optional `watched` callback in options:
 ```typescript
 const store = createStore(initialValue, {

package/.github/copilot-instructions.md

@@ -15,8 +15,8 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 ### Signal Types (all in `src/nodes/`)
 - **State** (`createState`): Mutable signals for values (`get`, `set`, `update`)
 - **Sensor** (`createSensor`): Read-only signals for external input with automatic state updates. Use `SKIP_EQUALITY` for mutable object observation.
-- **Memo** (`createMemo`): Synchronous derived computations with memoization and reducer capabilities
-- **Task** (`createTask`): Async derived computations with automatic AbortController cancellation
+- **Memo** (`createMemo`): Synchronous derived computations with memoization, reducer capabilities, and optional `watched(invalidate)` for external invalidation
+- **Task** (`createTask`): Async derived computations with automatic AbortController cancellation and optional `watched(invalidate)` for external invalidation
 - **Store** (`createStore`): Proxy-based reactive objects with per-property State/Store signals
 - **List** (`createList`): Reactive arrays with stable keys and per-item State signals
 - **Collection** (`createCollection`): Reactive collections — either externally-driven with watched lifecycle, or derived from List/Collection with item-level memoization
@@ -72,7 +72,8 @@ Cause & Effect is a reactive state management library for JavaScript/TypeScript
 - All signals have `.get()` for value access
 - Mutable signals (State) have `.set(value)` and `.update(fn)`
 - Store properties are automatically reactive signals via Proxy
-- Sensor/Collection use a start callback returning Cleanup (lazy activation)
+- Sensor/Collection use a watched callback returning Cleanup (lazy activation)
+- Memo/Task use optional `watched(invalidate)` callback in options for external invalidation
 - Store/List use optional `watched` callback in options returning Cleanup
 - Effects return a dispose function (Cleanup)
 
@@ -191,18 +192,27 @@ const count = createState(0, {
 ## Resource Management
 
 ```typescript
-// Sensor: lazy external input tracking
+// Sensor: lazy external input tracking (watched callback with set)
 const sensor = createSensor<T>((set) => {
   // setup — call set(value) to update
   return () => { /* cleanup — called when last effect stops watching */ }
 })
 
-// Collection: lazy external data source
+// Collection: lazy external data source (watched callback with applyChanges)
 const feed = createCollection<T>((applyChanges) => {
   // setup — call applyChanges(diffResult) on changes
   return () => { /* cleanup */ }
 }, { keyConfig: item => item.id })
 
+// Memo/Task: optional watched callback with invalidate
+const derived = createMemo(() => element.get().textContent ?? '', {
+  watched: (invalidate) => {
+    const obs = new MutationObserver(() => invalidate())
+    obs.observe(element.get(), { childList: true })
+    return () => obs.disconnect()
+  }
+})
+
 // Store/List: optional watched callback
 const store = createStore(initialValue, {
   watched: () => {

package/ARCHITECTURE.md

@@ -178,14 +178,14 @@ A mutable value container. The simplest signal type — `get()` links and return
 
 **Graph node**: `StateNode<T>` (source only)
 
-A read-only signal that tracks external input. The `start` callback receives a `set` function that updates the node's value via `setState()`. Sensors cover two patterns:
+A read-only signal that tracks external input. The `watched` callback receives a `set` function that updates the node's value via `setState()`. Sensors cover two patterns:
 
-1. **Tracking external values** (default): Receives replacement values from events (mouse position, resize events). Equality checking (`Object.is` by default) prevents unnecessary propagation.
+1. **Tracking external values** (default): Receives replacement values from events (mouse position, resize events). Equality checking (`===` by default) prevents unnecessary propagation.
 2. **Observing mutable objects** (with `SKIP_EQUALITY`): Holds a stable reference to a mutable object (DOM element, Map, Set). `set(sameRef)` with `equals: SKIP_EQUALITY` always propagates, notifying consumers that the object's internals have changed.
 
-The value starts undefined unless `options.value` is provided. Reading a sensor before its `start` callback has called `set()` (and without `options.value`) throws `UnsetSignalValueError`.
+The value starts undefined unless `options.value` is provided. Reading a sensor before its `watched` callback has called `set()` (and without `options.value`) throws `UnsetSignalValueError`.
 
-**Lazy lifecycle**: The `start` callback is invoked on first sink attachment. The returned cleanup is stored as `node.stop` and called when the last sink detaches (via `unlink()`).
+**Lazy lifecycle**: The `watched` callback is invoked on first sink attachment. The returned cleanup is stored as `node.stop` and called when the last sink detaches (via `unlink()`).
 
 ### Memo (`src/nodes/memo.ts`)
 
@@ -199,6 +199,8 @@ The `error` field preserves thrown errors: if `fn` throws, the error is stored a
 
 **Reducer pattern**: The `prev` parameter enables state accumulation across recomputations without writable state.
 
+**Watched lifecycle**: An optional `watched` callback in options provides lazy external invalidation. The callback receives an `invalidate` function and is invoked on first sink attachment. Calling `invalidate()` marks the node `FLAG_DIRTY`, propagates to sinks, and flushes — triggering re-evaluation of the memo's `fn` without changing any tracked dependency. The returned cleanup is stored as `node.stop` and called when the last sink detaches. This enables patterns like DOM observation (MutationObserver) where the memo re-derives its value in response to external events.
+
 ### Task (`src/nodes/task.ts`)
 
 **Graph node**: `TaskNode<T>` (source + sink)
@@ -209,6 +211,8 @@ During dependency tracking, only the synchronous preamble of `fn` is tracked (be
 
 `isPending()` returns `true` while a computation is in flight. `abort()` cancels the current computation manually. Errors are preserved like Memo, but old values are retained on errors (the last successful result remains accessible).
 
+**Watched lifecycle**: Same pattern as Memo — an optional `watched` callback receives `invalidate` and is invoked on first sink attachment. Calling `invalidate()` marks the node dirty and triggers re-execution, which aborts any in-flight computation via the existing `AbortController` mechanism before starting a new one.
+
 ### Effect (`src/nodes/effect.ts`)
 
 **Graph node**: `EffectNode` (sink only)
@@ -247,13 +251,13 @@ A reactive array with stable keys and per-item reactivity. Each item becomes a `
 
 Collection implements two creation patterns that share the same `Collection<T>` interface:
 
-#### `createCollection(start, options?)` — externally driven
+#### `createCollection(watched, options?)` — externally driven
 
 **Graph node**: `MemoNode<T[]>` (source + sink, tracks item values)
 
-An externally-driven reactive collection with a watched lifecycle, mirroring `createSensor(start, options?)`. The `start` callback receives an `applyChanges(diffResult)` function for granular add/change/remove operations. Initial items are provided via `options.value` (default `[]`).
+An externally-driven reactive collection with a watched lifecycle, mirroring `createSensor(watched, options?)`. The `watched` callback receives an `applyChanges(diffResult)` function for granular add/change/remove operations. Initial items are provided via `options.value` (default `[]`).
 
-**Lazy lifecycle**: Like Sensor, the `start` callback is invoked on first sink attachment. The returned cleanup is stored as `node.stop` and called when the last sink detaches (via `unlink()`). The `startWatching()` guard ensures `start` fires before `link()` so synchronous mutations inside `start` update `node.value` before the activating effect reads it.
+**Lazy lifecycle**: Like Sensor, the `watched` callback is invoked on first sink attachment. The returned cleanup is stored as `node.stop` and called when the last sink detaches (via `unlink()`). The `startWatching()` guard ensures `watched` fires before `link()` so synchronous mutations inside `watched` update `node.value` before the activating effect reads it.
 
 **External mutation via `applyChanges`**: Additions create new item signals (via configurable `createItem` factory, default `createState`). Changes update existing `State` signals. Removals delete signals and keys. Structural changes null out `node.sources` to force edge re-establishment. The node uses `equals: () => false` since structural changes are managed externally rather than detected by diffing.
 
@@ -261,14 +265,12 @@ An externally-driven reactive collection with a watched lifecycle, mirroring `cr
 
 #### `deriveCollection(source, callback)` — internally derived
 
-**Graph node**: `MemoNode<string[]>` (source + sink, tracks keys not values)
+**Graph node**: `MemoNode<T[]>` (source + sink, tracks item values)
 
 An internal factory (not exported from the public API) that creates a read-only derived transformation of a List or another Collection. Exposed to users via the `.deriveCollection(callback)` method on List and Collection. Each source item is individually memoized: sync callbacks create `Memo` signals, async callbacks create `Task` signals.
 
-**Two-level reactivity**: The derived collection's `MemoNode` tracks structural changes only — its `fn` (`syncKeys`) reads `source.keys()` to detect additions and removals. Value-level changes flow through the individual per-item `Memo`/`Task` signals, which independently track their source item.
-
-**Key differences from Store/List**: The `MemoNode.value` is a `string[]` (the keys array), not the collection's actual values. The `equals` function is a shallow string array comparison (`keysEqual`). The node starts `FLAG_DIRTY` (unlike Store/List which start clean after initialization) to ensure the first `refresh()` establishes the edge from source to collection.
+**Consistent with Store/List/createCollection**: The `MemoNode.value` is a `T[]` (cached computed values), and keys are tracked in a separate local `string[]` variable. The `equals` function uses shallow reference equality on array elements to prevent unnecessary downstream propagation when re-evaluation produces the same item references. The node starts `FLAG_DIRTY` to ensure the first `refresh()` establishes edges.
 
-**No `invalidateEdges`**: Unlike Store/List, the derived collection never needs to re-establish its source edge because it has exactly one source (the parent List or Collection) that never changes identity. Structural changes (adding/removing per-item signals) happen inside `syncKeys` without affecting the source edge.
+**Two-path access with structural fallback**: Same pattern as Store/List — first `get()` uses `refresh()` to establish edges; subsequent reads use `untrack(buildValue)`. A `syncKeys()` step inside `buildValue` syncs the signals map with `source.keys()`. If keys changed, `syncKeys` nulls `node.sources` to force edge re-establishment via `refresh()`, ensuring new child signals are properly linked.
 
-**Chaining**: `.deriveCollection()` creates a new derived collection from an existing one, forming a pipeline. Each level in the chain has its own `MemoNode` for structural tracking and its own set of per-item derived signals.
+**Chaining**: `.deriveCollection()` creates a new derived collection from an existing one, forming a pipeline. Each level in the chain has its own `MemoNode` for value caching and its own set of per-item derived signals.

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.18.1
+
+### Added
+
+- **Memo `watched(invalidate)` option**: `createMemo(fn, { watched })` accepts a lazy lifecycle callback that receives an `invalidate` function. Calling `invalidate()` marks the memo dirty and triggers re-evaluation. The callback is invoked on first sink attachment and cleaned up when the last sink detaches. This enables patterns like DOM observation where a memo re-derives its value in response to external events (e.g., MutationObserver) without needing a separate Sensor.
+- **Task `watched(invalidate)` option**: Same pattern as Memo. Calling `invalidate()` aborts any in-flight computation and triggers re-execution.
+- **`CollectionChanges<T>` type**: New typed interface for collection mutations with `add?: T[]`, `change?: T[]`, `remove?: T[]` arrays. Replaces the untyped `DiffResult` records previously used by `CollectionCallback`.
+- **`SensorOptions<T>` type**: Dedicated options type for `createSensor`, extending `SignalOptions<T>` with optional `value`.
+- **`CollectionChanges` export** from public API (`index.ts`).
+- **`SensorOptions` export** from public API (`index.ts`).
+
+### Changed
+
+- **`createSensor` parameter renamed**: `start` → `watched` for consistency with Store/List lifecycle terminology.
+- **`createSensor` options type**: `ComputedOptions<T>` → `SensorOptions<T>`. This decouples Sensor options from `ComputedOptions`, which now carries the `watched(invalidate)` field for Memo/Task.
+- **`createCollection` parameter renamed**: `start` → `watched` for consistency.
+- **`CollectionCallback` is now generic**: `CollectionCallback` → `CollectionCallback<T>`. The `applyChanges` parameter accepts `CollectionChanges<T>` instead of `DiffResult`.
+- **`CollectionOptions.createItem` signature**: `(key: string, value: T) => Signal<T>` → `(value: T) => Signal<T>`. Key generation is now handled internally.
+- **`KeyConfig<T>` return type relaxed**: Key functions may now return `string | undefined`. Returning `undefined` falls back to synthetic key generation.
+
+### Removed
+
+- **`DiffResult` removed from public API**: No longer re-exported from `index.ts`. The type remains available from `src/nodes/list.ts` for internal use but is superseded by `CollectionChanges<T>` for collection mutations.
+
+## 0.18.0
+
+Baseline release. Factory function API (`createState`, `createMemo`, `createTask`, `createEffect`, `createStore`, `createList`, `createCollection`, `createSensor`) with linked-list graph engine.

package/CLAUDE.md

@@ -86,10 +86,10 @@ The generic constraint `T extends {}` is crucial - it excludes `null` and `undef
 ### Collection Architecture
 
 **Collections** (`createCollection`): Externally-driven collections with watched lifecycle
-- Created via `createCollection(start, options?)` — mirrors `createSensor(start, options?)`
-- The `start` callback receives an `applyChanges(diffResult)` function for granular add/change/remove operations
+- Created via `createCollection(watched, options?)` — mirrors `createSensor(watched, options?)`
+- The `watched` callback receives an `applyChanges(diffResult)` function for granular add/change/remove operations
 - `options.value` provides initial items (default `[]`), `options.keyConfig` configures key generation
-- Lazy activation: `start` callback invoked on first effect access, cleanup when unwatched
+- Lazy activation: `watched` callback invoked on first effect access, cleanup when unwatched
 
 **Derived Collections** (`deriveCollection`): Transformed from Lists or other Collections
 - Created via `list.deriveCollection(callback)` or `collection.deriveCollection(callback)`
@@ -124,7 +124,7 @@ Computed signals implement smart memoization:
 
 ## Resource Management with Watch Callbacks
 
-Sensor and Collection signals use a **start callback** pattern for lazy resource management. Resources are allocated only when a signal is first accessed by an effect and automatically cleaned up when no effects are watching:
+Sensor, Collection, Memo (with `watched` option), and Task (with `watched` option) use a **watched callback** pattern for lazy resource management. Resources are allocated only when a signal is first accessed by an effect and automatically cleaned up when no effects are watching:
 
 ```typescript
 // Sensor: track external input with state updates
@@ -164,9 +164,9 @@ const user = createStore({ name: 'Alice', email: 'alice@example.com' }, {
 ```
 
 **Watch Lifecycle**:
-1. First effect accesses signal → start/watched callback executed
+1. First effect accesses signal → watched callback executed
 2. Last effect stops watching → returned cleanup function executed
-3. New effect accesses signal → start/watched callback executed again
+3. New effect accesses signal → watched callback executed again
 
 This pattern enables **lazy resource allocation** - resources are only consumed when actually needed and automatically freed when no longer used.
 
@@ -230,7 +230,7 @@ const firstTodo = todoList.byKey('task1') // Access by stable key
 
 **Collection (`createCollection`)**:
 - Externally-driven keyed collections (WebSocket streams, SSE, external data feeds)
-- Mirrors `createSensor(start, options?)` — start callback pattern with watched lifecycle
+- Mirrors `createSensor(watched, options?)` — watched callback pattern with lazy lifecycle
 - Same `Collection` interface — `.get()`, `.byKey()`, `.keys()`, `.deriveCollection()`
 
 ```typescript
@@ -263,6 +263,7 @@ const processed = todoList
 **Memo (`createMemo`)**:
 - Synchronous derived computations with memoization
 - Reducer pattern with previous value access
+- Optional `watched(invalidate)` callback for lazy external invalidation (e.g., MutationObserver)
 
 ```typescript
 const doubled = createMemo(() => count.get() * 2)
@@ -283,6 +284,7 @@ const runningTotal = createMemo(prev => prev + currentValue.get(), { value: 0 })
 
 **Task (`createTask`)**:
 - Async computations with automatic cancellation
+- Optional `watched(invalidate)` callback for lazy external invalidation
 
 ```typescript
 const userData = createTask(async (prev, abort) => {

package/README.md

@@ -1,6 +1,6 @@
 # Cause & Effect
 
-Version 0.18.0
+Version 0.18.1
 
 **Cause & Effect** is a reactive state management primitives library for TypeScript. It provides the foundational building blocks for managing complex, dynamic, composite, and asynchronous state — correctly and performantly — in a unified signal graph.
 
@@ -266,7 +266,7 @@ Lists have `.keys()`, `.add()`, and `.remove()` methods like stores. Additionall
 
 ### Collection
 
-A reactive collection with item-level memoization. Collections can be externally-driven (via a start callback) or derived from a List or another Collection.
+A reactive collection with item-level memoization. Collections can be externally-driven (via a watched callback) or derived from a List or another Collection.
 
 **Externally-driven collections** receive data from external sources (WebSocket, Server-Sent Events, etc.) via `applyChanges()`:
 
@@ -277,7 +277,7 @@ const items = createCollection((applyChanges) => {
   const ws = new WebSocket('/items')
   ws.onmessage = (e) => {
     const { add, change, remove } = JSON.parse(e.data)
-    applyChanges({ changed: true, add, change, remove })
+    applyChanges({ add, change, remove })
   }
   return () => ws.close()
 }, { keyConfig: item => item.id })
@@ -285,7 +285,7 @@ const items = createCollection((applyChanges) => {
 createEffect(() => console.log('Items:', items.get()))
 ```
 
-The start callback activates lazily when the collection is first accessed by an effect and cleans up when no effects are watching. Options include `value` for initial items (default `[]`) and `keyConfig` for key generation.
+The watched callback activates lazily when the collection is first accessed by an effect and cleans up when no effects are watching. Options include `value` for initial items (default `[]`) and `keyConfig` for key generation.
 
 **Derived collections** transform Lists or other Collections via `.deriveCollection()`:
 
@@ -476,7 +476,7 @@ dispose() // Cleans up the effect and runs the returned cleanup
 
 ### Resource Management with Watch Callbacks
 
-Sensor and Collection signals use a **start callback** for lazy resource management. The callback runs when the signal is first accessed by an effect and the returned cleanup function runs when no effects are watching:
+Sensor and Collection signals use a **watched callback** for lazy resource management. The callback runs when the signal is first accessed by an effect and the returned cleanup function runs when no effects are watching:
 
 ```js
 import { createSensor, createCollection, createEffect } from '@zeix/cause-effect'
@@ -517,11 +517,29 @@ const user = createStore({ name: 'Alice' }, {
 })
 ```
 
+Memo and Task signals also support a `watched` option, but their callback receives an `invalidate` function that marks the signal dirty and triggers recomputation:
+
+```js
+const changes = createMemo((prev) => {
+  const next = new Set(parent.querySelectorAll(selector))
+  // ... diff prev vs next ...
+  return { current: next, added, removed }
+}, {
+  value: { current: new Set(), added: [], removed: [] },
+  watched: (invalidate) => {
+    const observer = new MutationObserver(() => invalidate())
+    observer.observe(parent, { childList: true, subtree: true })
+    return () => observer.disconnect()
+  }
+})
+```
+
 This pattern is ideal for:
 - Event listeners that should only be active when data is being watched
 - Network connections that can be lazily established
 - Expensive computations that should pause when not needed
 - External subscriptions (WebSocket, Server-Sent Events, etc.)
+- Computed signals that need to react to external events (DOM mutations, timers)
 
 ## Contributing & License
 

package/context7.json

@@ -0,0 +1,4 @@
+{
+	"url": "https://context7.com/zeixcom/cause-effect",
+	"public_key": "pk_opatBUM6blxfIrNVkGw84"
+}

package/examples/events-sensor.ts

@@ -0,0 +1,187 @@
+import { createSensor, isSensor, type Sensor } from '..'
+
+/* === Types === */
+
+type ReservedWords =
+	| 'constructor'
+	| 'prototype'
+	| '__proto__'
+	| 'toString'
+	| 'valueOf'
+	| 'hasOwnProperty'
+	| 'isPrototypeOf'
+	| 'propertyIsEnumerable'
+	| 'toLocaleString'
+
+type ComponentProp = Exclude<string, keyof HTMLElement | ReservedWords>
+type ComponentProps = Record<ComponentProp, NonNullable<unknown>>
+
+type Component<P extends ComponentProps> = HTMLElement & P
+
+type UI = Record<string, Element | Sensor<Element[]>>
+
+type EventType<K extends string> = K extends keyof HTMLElementEventMap
+	? HTMLElementEventMap[K]
+	: Event
+
+type EventHandler<
+	T extends {},
+	Evt extends Event,
+	U extends UI,
+	E extends Element,
+> = (context: {
+	event: Evt
+	ui: U
+	target: E
+	prev: T
+}) => T | void | Promise<void>
+
+type EventHandlers<T extends {}, U extends UI, E extends Element> = {
+	[K in keyof HTMLElementEventMap]?: EventHandler<T, EventType<K>, U, E>
+}
+
+type ElementFromKey<U extends UI, K extends keyof U> = NonNullable<
+	U[K] extends Sensor<infer E extends Element>
+		? E
+		: U[K] extends Element
+			? U[K]
+			: never
+>
+
+type Parser<T extends {}, U extends UI> = (
+	ui: U,
+	value: string | null | undefined,
+	old?: string | null,
+) => T
+
+type Reader<T extends {}, U extends UI> = (ui: U) => T
+type Fallback<T extends {}, U extends UI> = T | Reader<T, U>
+
+type ParserOrFallback<T extends {}, U extends UI> =
+	| Parser<T, U>
+	| Fallback<T, U>
+
+/* === Internal === */
+
+const pendingElements = new Set<Element>()
+const tasks = new WeakMap<Element, () => void>()
+let requestId: number | undefined
+
+const runTasks = () => {
+	requestId = undefined
+	const elements = Array.from(pendingElements)
+	pendingElements.clear()
+	for (const element of elements) tasks.get(element)?.()
+}
+
+const requestTick = () => {
+	if (requestId) cancelAnimationFrame(requestId)
+	requestId = requestAnimationFrame(runTasks)
+}
+
+const schedule = (element: Element, task: () => void) => {
+	tasks.set(element, task)
+	pendingElements.add(element)
+	requestTick()
+}
+
+// High-frequency events that are passive by default and should be scheduled
+const PASSIVE_EVENTS = new Set([
+	'scroll',
+	'resize',
+	'mousewheel',
+	'touchstart',
+	'touchmove',
+	'wheel',
+])
+
+const isReader = <T extends {}, U extends UI>(
+	value: unknown,
+): value is Reader<T, U> => typeof value === 'function'
+
+const getFallback = <T extends {}, U extends UI>(
+	ui: U,
+	fallback: ParserOrFallback<T, U>,
+): T => (isReader<T, U>(fallback) ? fallback(ui) : (fallback as T))
+
+/* === Exported Functions === */
+
+/**
+ * Produce an event-driven sensor from transformed event data
+ *
+ * @since 0.16.0
+ * @param {S} key - name of UI key
+ * @param {ParserOrFallback<T>} init - Initial value, reader or parser
+ * @param {EventHandlers<T, ElementFromSelector<S>, C>} events - Transformation functions for events
+ * @returns {Extractor<Sensor<T>, C>} Extractor function for value from event
+ */
+const createEventsSensor =
+	<T extends {}, P extends ComponentProps, U extends UI, K extends keyof U>(
+		init: ParserOrFallback<T, U>,
+		key: K,
+		events: EventHandlers<T, U, ElementFromKey<U, K>>,
+	): ((ui: U & { host: Component<P> }) => Sensor<T>) =>
+	(ui: U & { host: Component<P> }) => {
+		const { host } = ui
+		let value: T = getFallback(ui, init)
+		const targets = isSensor<ElementFromKey<U, K>[]>(ui[key])
+			? ui[key].get()
+			: [ui[key] as ElementFromKey<U & { host: Component<P> }, K>]
+		const eventMap = new Map<string, EventListener>()
+
+		const getTarget = (
+			eventTarget: Node,
+		): ElementFromKey<U, K> | undefined => {
+			for (const t of targets)
+				if (t.contains(eventTarget)) return t as ElementFromKey<U, K>
+		}
+
+		return createSensor<T>(
+			set => {
+				for (const [type, handler] of Object.entries(events)) {
+					const options = { passive: PASSIVE_EVENTS.has(type) }
+					const listener = (e: Event) => {
+						const eventTarget = e.target as Node
+						if (!eventTarget) return
+						const target = getTarget(eventTarget)
+						if (!target) return
+						e.stopPropagation()
+
+						const task = () => {
+							try {
+								const next = handler({
+									event: e as any,
+									ui,
+									target,
+									prev: value,
+								})
+								if (next == null || next instanceof Promise)
+									return
+								if (!Object.is(next, value)) {
+									value = next
+									set(next)
+								}
+							} catch (error) {
+								e.stopImmediatePropagation()
+								throw error
+							}
+						}
+						if (options.passive) schedule(host, task)
+						else task()
+					}
+					eventMap.set(type, listener)
+					host.addEventListener(type, listener, options)
+				}
+				return () => {
+					if (eventMap.size) {
+						for (const [type, listener] of eventMap)
+							host.removeEventListener(type, listener)
+						eventMap.clear()
+					}
+				}
+			},
+			{ value },
+		)
+	}
+
+export { createEventsSensor, type EventHandler, type EventHandlers }