@mindees/core 0.13.0 → 0.15.0

package/README.md

@@ -4,12 +4,17 @@ The reactive runtime foundation of MindeesNative — a fast, fine-grained
 **signals** library (the same reactivity model behind SolidJS and modern
 frameworks), written in strict TypeScript.
 
-> **Status: 🧪 Experimental (Phases 1–2).** Implemented and thoroughly tested:
+> **Status: 🧪 Experimental (pre-1.0).** Implemented and thoroughly tested:
 > the **reactivity** layer (`signal`, `computed`/`memo`, `effect`, `batch`,
-> `untrack`, `createRoot`, `onCleanup`), the **component model** (element tree +
-> selector-based, re-render-isolated context), the **priority scheduler**, and a
-> **thread-pool** abstraction (Web Worker backend + inline fallback). APIs may
-> still change before `1.0`.
+> `untrack`, `createRoot`, `onCleanup`, plus `startTransition`/`deferred` and a
+> pluggable reactive scheduler), the **component model** (element tree +
+> selector-based, re-render-isolated context, portals, keyed regions), the
+> **priority scheduler**, a **thread-pool** abstraction (Web Worker backend +
+> inline fallback), the **animation engine** (reactive animated values with
+> timing/spring drivers + `interpolate`, RN `Animated`/Reanimated + Flutter
+> `AnimationController` parity), and **gesture recognizers** (tap, longPress,
+> pan, pinch, swipe → reactive state, RN Gesture Handler / Flutter
+> `GestureDetector` parity). APIs may still change before `1.0`.
 
 ## Install
 
@@ -63,6 +68,9 @@ depend on a changed value re-run — no virtual-DOM diffing, no manual
 | `effect(fn)` | fn | Re-runs on dependency change; returns a disposer; supports `onCleanup`. |
 | `batch(fn)` | fn | Coalesce writes; effects run once at the end. |
 | `untrack(fn)` | fn | Read without subscribing. |
+| `startTransition(fn)` | fn | Mark writes as low-priority (deferred) updates. |
+| `deferred(source)` | fn | A derived accessor that lags `source` to a lower priority lane. |
+| `setReactiveScheduler(s)` | fn | Route reactive effects through a custom `Scheduler` (or `null` to reset). |
 | `createRoot(fn)` | fn | Non-tracked owner scope with manual `dispose`. |
 | `onCleanup(fn)` | fn | Register teardown for the current scope. |
 | `getOwner` / `runWithOwner` | fn | Inspect / re-enter an ownership scope. |
@@ -101,6 +109,8 @@ await pool.run((n) => fib(n), 40)
 | --- | --- | --- |
 | `createElement` / `Fragment` / `isElement` | fn | Renderer-agnostic element tree. |
 | `createContext` / `createProvider` | fn | Selector-based, **re-render-isolated** context. |
+| `portal` / `isPortal` | fn | Render a subtree into a different host region (overlays/modals/toasts). |
+| `keyedRegion` / `isKeyedRegion` | fn | Keyed list region for stable, reconciled reordering. |
 | `renderComponent` | fn | Run a component in a disposable owner scope. |
 | `createScheduler` / `Scheduler` | fn | Two-lane priority scheduler (cancellable, dedupable). |
 | `createWorkerPool` / `createInlineThreadPool` | fn | `ThreadPool` backends (web + fallback). |
@@ -109,6 +119,61 @@ await pool.run((n) => fib(n), 40)
 > Native multi-threading is a **research track** (honest `NotImplementedError`);
 > the Web Worker and inline backends work today.
 
+## Animation engine
+
+RN `Animated`/Reanimated + Flutter `AnimationController` parity, built entirely on
+the reactive core. An `AnimatedValue` **is a signal**, so reading it inside a
+`style` accessor re-renders only that node. One injected `FrameSource` drives a
+single loop that ticks every active driver inside one `batch()` per frame — so a
+style reading several animated values recomputes once (glitch-free). With no frame
+source (SSR / headless / tests until one is wired), animations **jump to their
+final value** synchronously: deterministic, never a hang.
+
+```ts
+import { animate, timing, spring, interpolate } from '@mindees/core'
+
+const x = animate(0)
+timing(x, { to: 100, duration: 250 })      // duration driver
+spring(x, { to: 100, stiffness: 180 })     // physics driver (velocity-preserving)
+
+const opacity = interpolate(x, [0, 100], [0, 1]) // map a range to a range
+```
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `animate(initial)` | fn | Create a reactive `AnimatedValue` (a signal you can drive). |
+| `timing` / `spring` | fn | Duration and physics drivers; return an `AnimationHandle` (`stop()` + awaitable `done`). |
+| `interpolate(src, inRange, outRange)` | fn | Map an input range to an output range. |
+| `linear` / `easeInQuad` / `easeOutQuad` / `easeInOutQuad` / `easeOutCubic` / `cubicBezier` | fn | Easing curves. |
+| `setFrameSource` / `getFrameSource` / `rafFrameSource` / `manualFrameSource` | fn | Inject the per-frame clock (rAF on web, vsync on native, manual in tests). |
+
+## Gesture recognizers
+
+RN Gesture Handler / Flutter `GestureDetector` parity, built on the reactive core.
+Each factory returns a `Recognizer`: a bag of pointer-event handlers to spread onto
+a host element, plus **reactive state** (signals) you read in a `style` accessor or
+feed straight into the animation engine. The only platform-aware code is
+`normalizePointer`, so recognizers run on web (Pointer Events), native (the
+command-backend payload), and tests (synthetic events), and SSR safely.
+
+```ts
+import { pan, tap, composeGestures } from '@mindees/core'
+
+const drag = pan({ axis: 'both' })
+// drag.state is a bag of accessor signals: drag.state.translationX(), .active(), …
+// spread drag.handlers onto a host element. Compose recognizers onto ONE element
+// (the renderer binds a single listener per event, so spreading two would drop one):
+const merged = composeGestures([drag, tap({})])
+// → spread merged.handlers; read each recognizer's own .state
+```
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `tap` / `longPress` / `pan` / `pinch` / `swipe` | fn | Recognizers → `{ handlers, state }`; `state` is a bag of accessor signals. |
+| `panAnimated(x, y, opts?)` | fn | A pan recognizer wired to drive two `AnimatedValue`s directly (with optional release snap). |
+| `composeGestures(recognizers)` | fn | Merge an array of recognizers onto one element (one listener per event). |
+| `normalizePointer` | fn | Platform-agnostic pointer-sample normalization. |
+
 ## License
 
 `MIT OR Apache-2.0`

package/dist/index.d.ts

@@ -14,7 +14,7 @@ import { ThreadPool, WorkerLike, WorkerPoolOptions, createInlineThreadPool, crea
 /** The npm package name. */
 declare const name = "@mindees/core";
 /** The package version. All `@mindees/*` packages share one locked version line. */
-declare const VERSION = "0.13.0";
+declare const VERSION = "0.15.0";
 /**
  * Current maturity of this package. See the repository `STATUS.md`.
  *

package/dist/index.js

@@ -12,7 +12,7 @@ import { createInlineThreadPool, createNativeThreadPool, createWorkerPool } from
 /** The npm package name. */
 const name = "@mindees/core";
 /** The package version. All `@mindees/*` packages share one locked version line. */
-const VERSION = "0.13.0";
+const VERSION = "0.15.0";
 /**
 * Current maturity of this package. See the repository `STATUS.md`.
 *

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { Maturity, PackageInfo } from './types'\n\n/**\n * Animation engine: reactive animated values + timing/spring drivers + interpolate, driven by an\n * injected frame source (RN Animated/Reanimated + Flutter AnimationController parity).\n */\nexport {\n  _activeAnimationCount,\n  _resetAnimation,\n  type AnimatedValue,\n  type AnimationHandle,\n  animate,\n  cubicBezier,\n  type Easing,\n  easeInOutQuad,\n  easeInQuad,\n  easeOutCubic,\n  easeOutQuad,\n  type FrameSource,\n  getFrameSource,\n  interpolate,\n  linear,\n  manualFrameSource,\n  rafFrameSource,\n  setFrameSource,\n  spring,\n  timing,\n} from './animation'\n/**\n * Component model: a renderer-agnostic element tree plus selector-based,\n * re-render-isolated context. (Phase 2)\n */\nexport {\n  type Component,\n  type Context,\n  type ContextProvider,\n  createContext,\n  createElement,\n  createProvider,\n  ELEMENT_TYPE,\n  type ElementType,\n  Fragment,\n  hasOwner,\n  isElement,\n  isKeyedRegion,\n  isPortal,\n  KEYED_REGION,\n  type KeyedRegion,\n  type KeyedRegionOptions,\n  keyedRegion,\n  type MindeesElement,\n  type MindeesNode,\n  PORTAL,\n  type PortalRegion,\n  portal,\n  renderComponent,\n  type SelectorEquals,\n} from './component'\nexport { NotImplementedError } from './errors'\n/**\n * Gesture recognizers: tap/longPress/pan/pinch/swipe → reactive state that drives styles and the\n * animation engine (RN Gesture Handler / Flutter GestureDetector parity).\n */\nexport {\n  _setGestureClock,\n  composeGestures,\n  type GestureHandlers,\n  longPress,\n  normalizePointer,\n  type PanEvent,\n  type PanState,\n  type PinchEvent,\n  type PinchState,\n  type PointerSample,\n  pan,\n  panAnimated,\n  pinch,\n  type Recognizer,\n  type SwipeDirection,\n  type SwipeEvent,\n  swipe,\n  type TapState,\n  tap,\n} from './gesture'\nexport { notImplemented } from './not-implemented'\n/**\n * Fine-grained reactivity: signals, computed values, effects, batching, and\n * disposal scopes. This is the reactive core of MindeesNative.\n */\nexport {\n  type Accessor,\n  batch,\n  type ComputedOptions,\n  computed,\n  createRoot,\n  deferred,\n  type EffectOptions,\n  type EqualsFn,\n  effect,\n  getOwner,\n  type Memo,\n  memo,\n  type Owner,\n  onCleanup,\n  runWithOwner,\n  type Signal,\n  type SignalOptions,\n  setReactiveScheduler,\n  signal,\n  startTransition,\n  untrack,\n} from './reactive'\n/**\n * Priority scheduler: two-lane (sync/normal), microtask-batched, with\n * cancellable and dedupable tasks. (Phase 2)\n */\nexport {\n  createScheduler,\n  type Priority,\n  type ScheduledTask,\n  type ScheduleOptions,\n  Scheduler,\n  type SchedulerOptions,\n  type Task,\n} from './scheduler'\n/**\n * Threading abstraction: a {@link ThreadPool} contract with a working Web Worker\n * backend and an inline fallback. Native multi-threading is a research track. (Phase 2)\n */\nexport {\n  createInlineThreadPool,\n  createNativeThreadPool,\n  createWorkerPool,\n  type ThreadPool,\n  type WorkerLike,\n  type WorkerPoolOptions,\n} from './threading'\nexport type { Maturity, PackageInfo } from './types'\n\n/** The npm package name. */\nexport const name = '@mindees/core'\n\n/** The package version. All `@mindees/*` packages share one locked version line. */\nexport const VERSION = '0.13.0'\n\n/**\n * Current maturity of this package. See the repository `STATUS.md`.\n *\n * The reactivity layer (signals/computed/effect/batch), the component model with\n * selector-isolated context, the priority scheduler, and the thread-pool\n * abstraction (Web Worker + inline) are all implemented and tested. Native\n * multi-threading remains a research track (throws `NotImplementedError`).\n */\nexport const maturity: Maturity = 'experimental'\n\n/**\n * Static identity + maturity metadata for this package. Frozen so the\n * self-reported identity tooling introspects cannot be mutated at runtime,\n * matching the `readonly` fields of {@link PackageInfo}.\n */\nexport const info: PackageInfo = Object.freeze({ name, version: VERSION, maturity })\n"],"mappings":";;;;;;;;;;;;AA4IA,MAAa,OAAO;;AAGpB,MAAa,UAAU;;;;;;;;;AAUvB,MAAa,WAAqB;;;;;;AAOlC,MAAa,OAAoB,OAAO,OAAO;CAAE;CAAM,SAAS;CAAS;AAAS,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { Maturity, PackageInfo } from './types'\n\n/**\n * Animation engine: reactive animated values + timing/spring drivers + interpolate, driven by an\n * injected frame source (RN Animated/Reanimated + Flutter AnimationController parity).\n */\nexport {\n  _activeAnimationCount,\n  _resetAnimation,\n  type AnimatedValue,\n  type AnimationHandle,\n  animate,\n  cubicBezier,\n  type Easing,\n  easeInOutQuad,\n  easeInQuad,\n  easeOutCubic,\n  easeOutQuad,\n  type FrameSource,\n  getFrameSource,\n  interpolate,\n  linear,\n  manualFrameSource,\n  rafFrameSource,\n  setFrameSource,\n  spring,\n  timing,\n} from './animation'\n/**\n * Component model: a renderer-agnostic element tree plus selector-based,\n * re-render-isolated context. (Phase 2)\n */\nexport {\n  type Component,\n  type Context,\n  type ContextProvider,\n  createContext,\n  createElement,\n  createProvider,\n  ELEMENT_TYPE,\n  type ElementType,\n  Fragment,\n  hasOwner,\n  isElement,\n  isKeyedRegion,\n  isPortal,\n  KEYED_REGION,\n  type KeyedRegion,\n  type KeyedRegionOptions,\n  keyedRegion,\n  type MindeesElement,\n  type MindeesNode,\n  PORTAL,\n  type PortalRegion,\n  portal,\n  renderComponent,\n  type SelectorEquals,\n} from './component'\nexport { NotImplementedError } from './errors'\n/**\n * Gesture recognizers: tap/longPress/pan/pinch/swipe → reactive state that drives styles and the\n * animation engine (RN Gesture Handler / Flutter GestureDetector parity).\n */\nexport {\n  _setGestureClock,\n  composeGestures,\n  type GestureHandlers,\n  longPress,\n  normalizePointer,\n  type PanEvent,\n  type PanState,\n  type PinchEvent,\n  type PinchState,\n  type PointerSample,\n  pan,\n  panAnimated,\n  pinch,\n  type Recognizer,\n  type SwipeDirection,\n  type SwipeEvent,\n  swipe,\n  type TapState,\n  tap,\n} from './gesture'\nexport { notImplemented } from './not-implemented'\n/**\n * Fine-grained reactivity: signals, computed values, effects, batching, and\n * disposal scopes. This is the reactive core of MindeesNative.\n */\nexport {\n  type Accessor,\n  batch,\n  type ComputedOptions,\n  computed,\n  createRoot,\n  deferred,\n  type EffectOptions,\n  type EqualsFn,\n  effect,\n  getOwner,\n  type Memo,\n  memo,\n  type Owner,\n  onCleanup,\n  runWithOwner,\n  type Signal,\n  type SignalOptions,\n  setReactiveScheduler,\n  signal,\n  startTransition,\n  untrack,\n} from './reactive'\n/**\n * Priority scheduler: two-lane (sync/normal), microtask-batched, with\n * cancellable and dedupable tasks. (Phase 2)\n */\nexport {\n  createScheduler,\n  type Priority,\n  type ScheduledTask,\n  type ScheduleOptions,\n  Scheduler,\n  type SchedulerOptions,\n  type Task,\n} from './scheduler'\n/**\n * Threading abstraction: a {@link ThreadPool} contract with a working Web Worker\n * backend and an inline fallback. Native multi-threading is a research track. (Phase 2)\n */\nexport {\n  createInlineThreadPool,\n  createNativeThreadPool,\n  createWorkerPool,\n  type ThreadPool,\n  type WorkerLike,\n  type WorkerPoolOptions,\n} from './threading'\nexport type { Maturity, PackageInfo } from './types'\n\n/** The npm package name. */\nexport const name = '@mindees/core'\n\n/** The package version. All `@mindees/*` packages share one locked version line. */\nexport const VERSION = '0.15.0'\n\n/**\n * Current maturity of this package. See the repository `STATUS.md`.\n *\n * The reactivity layer (signals/computed/effect/batch), the component model with\n * selector-isolated context, the priority scheduler, and the thread-pool\n * abstraction (Web Worker + inline) are all implemented and tested. Native\n * multi-threading remains a research track (throws `NotImplementedError`).\n */\nexport const maturity: Maturity = 'experimental'\n\n/**\n * Static identity + maturity metadata for this package. Frozen so the\n * self-reported identity tooling introspects cannot be mutated at runtime,\n * matching the `readonly` fields of {@link PackageInfo}.\n */\nexport const info: PackageInfo = Object.freeze({ name, version: VERSION, maturity })\n"],"mappings":";;;;;;;;;;;;AA4IA,MAAa,OAAO;;AAGpB,MAAa,UAAU;;;;;;;;;AAUvB,MAAa,WAAqB;;;;;;AAOlC,MAAa,OAAoB,OAAO,OAAO;CAAE;CAAM,SAAS;CAAS;AAAS,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindees/core",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "MindeesNative core — fine-grained reactivity (signals/computed/effect/batch), component model with selector-isolated context, priority scheduler, and a thread-pool abstraction (Web Worker + inline; native is a research track).",
   "license": "MIT OR Apache-2.0",
   "type": "module",