@mindees/core 0.1.0

package/dist/scheduler/scheduler.d.ts

@@ -0,0 +1,86 @@
+//#region src/scheduler/scheduler.d.ts
+/**
+ * MindeesNative scheduler — a small, deterministic priority scheduler.
+ *
+ * Two lanes:
+ * - **`sync`** — high-priority work (interaction handlers, first frame). Drained
+ *   synchronously at the next flush point and always before the normal lane.
+ * - **`normal`** — default work, drained on a microtask so multiple schedules in
+ *   the same tick coalesce into one flush.
+ *
+ * Tasks are **cancellable** (via the returned handle) and **dedupable** (two
+ * tasks scheduled with the same `key` collapse to one — the latest callback
+ * wins, preserving the earlier queue position). The scheduler never throws from
+ * a task into the caller: task errors are collected and reported via an optional
+ * `onError` hook, so one bad task can't stop the rest of the flush.
+ *
+ * @module
+ */
+/** Scheduling lanes, highest priority first. */
+type Priority = 'sync' | 'normal';
+/** A unit of scheduled work. */
+type Task = () => void;
+/** Options for {@link Scheduler.schedule}. */
+interface ScheduleOptions {
+  /** Lane to run in. Defaults to `'normal'`. */
+  priority?: Priority;
+  /**
+   * Dedup key. Scheduling again with the same key replaces the pending task's
+   * callback (latest wins) instead of enqueuing a second one.
+   */
+  key?: string;
+}
+/** A handle to a scheduled task. */
+interface ScheduledTask {
+  /** Remove the task if it hasn't run yet. Idempotent. */
+  cancel(): void;
+  /** Whether the task is still pending (not yet run or cancelled). */
+  readonly pending: boolean;
+}
+/** Options for {@link Scheduler}. */
+interface SchedulerOptions {
+  /**
+   * Called with any error thrown by a task. If omitted, errors are rethrown
+   * asynchronously (so they surface to the host without aborting the flush).
+   */
+  onError?: (error: unknown) => void;
+  /**
+   * Schedules a microtask. Injectable for testing; defaults to `queueMicrotask`.
+   */
+  scheduleMicrotask?: (cb: () => void) => void;
+}
+/**
+ * A deterministic two-lane priority scheduler. Create one with {@link createScheduler}.
+ */
+declare class Scheduler {
+  private readonly sync;
+  private readonly normal;
+  private readonly keyed;
+  private microtaskQueued;
+  private flushing;
+  private readonly onError;
+  private readonly scheduleMicrotask;
+  constructor(options?: SchedulerOptions);
+  /** Schedule `task`. Returns a handle to cancel it or check its status. */
+  schedule(task: Task, options?: ScheduleOptions): ScheduledTask;
+  /** Run all pending tasks right now (sync lane first), draining both lanes. */
+  flushSync(): void;
+  /** Number of pending tasks across both lanes (cancelled tasks excluded). */
+  get size(): number;
+  private requestFlush;
+  private run;
+  /**
+   * Remove an entry's dedup-key mapping, but only if the map still points at THIS
+   * entry. Keys are reused over time (a 'render' key is scheduled, runs, then
+   * scheduled again), so a stale handle or an already-dequeued entry must never
+   * evict a newer live entry's mapping — doing so would break dedup and let two
+   * same-key tasks both run.
+   */
+  private clearKey;
+  private makeHandle;
+}
+/** Create a new {@link Scheduler}. */
+declare function createScheduler(options?: SchedulerOptions): Scheduler;
+//#endregion
+export { Priority, ScheduleOptions, ScheduledTask, Scheduler, SchedulerOptions, Task, createScheduler };
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","names":[],"sources":["../../src/scheduler/scheduler.ts"],"mappings":";;AAmBA;;;;AAAoB;AAGpB;;;;AAAgB;AAGhB;;;;;;;KANY,QAAA;AAaP;AAAA,KAVO,IAAA;;UAGK,eAAA;EAaf;EAXA,QAAA,GAAW,QAAQ;EAsBJ;;;;EAjBf,GAAA;AAAA;;UAIe,aAAA;EAsBoB;EApBnC,MAAA;EAiCW;EAAA,SA/BF,OAAO;AAAA;;UASD,gBAAA;EAqCgB;;;;EAhC/B,OAAA,IAAW,KAAA;EAmBM;;;EAfjB,iBAAA,IAAqB,EAAA;AAAA;;;;cAaV,SAAA;EAAA,iBACM,IAAA;EAAA,iBACA,MAAA;EAAA,iBACA,KAAA;EAAA,QACT,eAAA;EAAA,QACA,QAAA;EAAA,iBACS,OAAA;EAAA,iBACA,iBAAA;cAEL,OAAA,GAAU,gBAAA;EAuDd;EAjDR,QAAA,CAAS,IAAA,EAAM,IAAA,EAAM,OAAA,GAAU,eAAA,GAAkB,aAAA;EAwFzC;EAnER,SAAA;EAyEkB;EAAA,IApDd,IAAA;EAAA,QAOI,YAAA;EAAA,QASA,GAAA;;;;;;;AAkD4D;UApB5D,QAAA;EAAA,QAMA,UAAA;AAAA;;iBAcM,eAAA,CAAgB,OAAA,GAAU,gBAAA,GAAmB,SAAS"}

package/dist/scheduler/scheduler.js

@@ -0,0 +1,118 @@
+//#region src/scheduler/scheduler.ts
+const defaultScheduleMicrotask = typeof queueMicrotask === "function" ? queueMicrotask : (cb) => {
+	Promise.resolve().then(cb);
+};
+/**
+* A deterministic two-lane priority scheduler. Create one with {@link createScheduler}.
+*/
+var Scheduler = class {
+	sync = [];
+	normal = [];
+	keyed = /* @__PURE__ */ new Map();
+	microtaskQueued = false;
+	flushing = false;
+	onError;
+	scheduleMicrotask;
+	constructor(options) {
+		this.onError = options?.onError;
+		this.scheduleMicrotask = options?.scheduleMicrotask ?? defaultScheduleMicrotask;
+	}
+	/** Schedule `task`. Returns a handle to cancel it or check its status. */
+	schedule(task, options) {
+		const priority = options?.priority ?? "normal";
+		const key = options?.key ?? null;
+		if (key !== null) {
+			const existing = this.keyed.get(key);
+			if (existing && existing.fn !== null) {
+				existing.fn = task;
+				return this.makeHandle(existing);
+			}
+		}
+		const entry = {
+			key,
+			fn: task
+		};
+		if (key !== null) this.keyed.set(key, entry);
+		(priority === "sync" ? this.sync : this.normal).push(entry);
+		this.requestFlush();
+		return this.makeHandle(entry);
+	}
+	/** Run all pending tasks right now (sync lane first), draining both lanes. */
+	flushSync() {
+		if (this.flushing) return;
+		this.flushing = true;
+		try {
+			while (this.sync.length > 0 || this.normal.length > 0) {
+				const entry = this.sync.length > 0 ? this.sync.shift() : this.normal.shift();
+				if (!entry) continue;
+				this.clearKey(entry);
+				const fn = entry.fn;
+				entry.fn = null;
+				if (fn) this.run(fn);
+			}
+		} finally {
+			this.flushing = false;
+			this.microtaskQueued = false;
+		}
+	}
+	/** Number of pending tasks across both lanes (cancelled tasks excluded). */
+	get size() {
+		let n = 0;
+		for (const e of this.sync) if (e.fn !== null) n++;
+		for (const e of this.normal) if (e.fn !== null) n++;
+		return n;
+	}
+	requestFlush() {
+		if (this.microtaskQueued || this.flushing) return;
+		this.microtaskQueued = true;
+		this.scheduleMicrotask(() => {
+			this.microtaskQueued = false;
+			this.flushSync();
+		});
+	}
+	run(fn) {
+		try {
+			fn();
+		} catch (error) {
+			if (this.onError) try {
+				this.onError(error);
+			} catch (hookError) {
+				this.scheduleMicrotask(() => {
+					throw hookError;
+				});
+			}
+			else this.scheduleMicrotask(() => {
+				throw error;
+			});
+		}
+	}
+	/**
+	* Remove an entry's dedup-key mapping, but only if the map still points at THIS
+	* entry. Keys are reused over time (a 'render' key is scheduled, runs, then
+	* scheduled again), so a stale handle or an already-dequeued entry must never
+	* evict a newer live entry's mapping — doing so would break dedup and let two
+	* same-key tasks both run.
+	*/
+	clearKey(entry) {
+		if (entry.key !== null && this.keyed.get(entry.key) === entry) this.keyed.delete(entry.key);
+	}
+	makeHandle(entry) {
+		return {
+			cancel: () => {
+				entry.fn = null;
+				this.clearKey(entry);
+			},
+			get pending() {
+				return entry.fn !== null;
+			}
+		};
+	}
+};
+/** Create a new {@link Scheduler}. */
+function createScheduler(options) {
+	return new Scheduler(options);
+}
+//#endregion
+export { Scheduler, createScheduler };
+
+//# sourceMappingURL=scheduler.js.map

package/dist/scheduler/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","names":[],"sources":["../../src/scheduler/scheduler.ts"],"sourcesContent":["/**\n * MindeesNative scheduler — a small, deterministic priority scheduler.\n *\n * Two lanes:\n * - **`sync`** — high-priority work (interaction handlers, first frame). Drained\n *   synchronously at the next flush point and always before the normal lane.\n * - **`normal`** — default work, drained on a microtask so multiple schedules in\n *   the same tick coalesce into one flush.\n *\n * Tasks are **cancellable** (via the returned handle) and **dedupable** (two\n * tasks scheduled with the same `key` collapse to one — the latest callback\n * wins, preserving the earlier queue position). The scheduler never throws from\n * a task into the caller: task errors are collected and reported via an optional\n * `onError` hook, so one bad task can't stop the rest of the flush.\n *\n * @module\n */\n\n/** Scheduling lanes, highest priority first. */\nexport type Priority = 'sync' | 'normal'\n\n/** A unit of scheduled work. */\nexport type Task = () => void\n\n/** Options for {@link Scheduler.schedule}. */\nexport interface ScheduleOptions {\n  /** Lane to run in. Defaults to `'normal'`. */\n  priority?: Priority\n  /**\n   * Dedup key. Scheduling again with the same key replaces the pending task's\n   * callback (latest wins) instead of enqueuing a second one.\n   */\n  key?: string\n}\n\n/** A handle to a scheduled task. */\nexport interface ScheduledTask {\n  /** Remove the task if it hasn't run yet. Idempotent. */\n  cancel(): void\n  /** Whether the task is still pending (not yet run or cancelled). */\n  readonly pending: boolean\n}\n\ninterface Entry {\n  key: string | null\n  fn: Task | null // null once cancelled\n}\n\n/** Options for {@link Scheduler}. */\nexport interface SchedulerOptions {\n  /**\n   * Called with any error thrown by a task. If omitted, errors are rethrown\n   * asynchronously (so they surface to the host without aborting the flush).\n   */\n  onError?: (error: unknown) => void\n  /**\n   * Schedules a microtask. Injectable for testing; defaults to `queueMicrotask`.\n   */\n  scheduleMicrotask?: (cb: () => void) => void\n}\n\nconst defaultScheduleMicrotask: (cb: () => void) => void =\n  typeof queueMicrotask === 'function'\n    ? queueMicrotask\n    : (cb) => {\n        void Promise.resolve().then(cb)\n      }\n\n/**\n * A deterministic two-lane priority scheduler. Create one with {@link createScheduler}.\n */\nexport class Scheduler {\n  private readonly sync: Entry[] = []\n  private readonly normal: Entry[] = []\n  private readonly keyed = new Map<string, Entry>()\n  private microtaskQueued = false\n  private flushing = false\n  private readonly onError: ((error: unknown) => void) | undefined\n  private readonly scheduleMicrotask: (cb: () => void) => void\n\n  constructor(options?: SchedulerOptions) {\n    this.onError = options?.onError\n    this.scheduleMicrotask = options?.scheduleMicrotask ?? defaultScheduleMicrotask\n  }\n\n  /** Schedule `task`. Returns a handle to cancel it or check its status. */\n  schedule(task: Task, options?: ScheduleOptions): ScheduledTask {\n    const priority = options?.priority ?? 'normal'\n    const key = options?.key ?? null\n\n    if (key !== null) {\n      const existing = this.keyed.get(key)\n      if (existing && existing.fn !== null) {\n        // Dedup: replace the callback, keep the existing queue position.\n        existing.fn = task\n        return this.makeHandle(existing)\n      }\n    }\n\n    const entry: Entry = { key, fn: task }\n    if (key !== null) this.keyed.set(key, entry)\n    ;(priority === 'sync' ? this.sync : this.normal).push(entry)\n    this.requestFlush()\n    return this.makeHandle(entry)\n  }\n\n  /** Run all pending tasks right now (sync lane first), draining both lanes. */\n  flushSync(): void {\n    if (this.flushing) return\n    this.flushing = true\n    try {\n      // Drain in priority order. Re-check each loop so tasks scheduled by tasks\n      // (e.g. a sync task that queues normal work) are handled in this flush.\n      while (this.sync.length > 0 || this.normal.length > 0) {\n        const entry = this.sync.length > 0 ? this.sync.shift() : this.normal.shift()\n        if (!entry) continue\n        this.clearKey(entry)\n        const fn = entry.fn\n        entry.fn = null\n        if (fn) this.run(fn)\n      }\n    } finally {\n      this.flushing = false\n      this.microtaskQueued = false\n    }\n  }\n\n  /** Number of pending tasks across both lanes (cancelled tasks excluded). */\n  get size(): number {\n    let n = 0\n    for (const e of this.sync) if (e.fn !== null) n++\n    for (const e of this.normal) if (e.fn !== null) n++\n    return n\n  }\n\n  private requestFlush(): void {\n    if (this.microtaskQueued || this.flushing) return\n    this.microtaskQueued = true\n    this.scheduleMicrotask(() => {\n      this.microtaskQueued = false\n      this.flushSync()\n    })\n  }\n\n  private run(fn: Task): void {\n    try {\n      fn()\n    } catch (error) {\n      if (this.onError) {\n        try {\n          this.onError(error)\n        } catch (hookError) {\n          // A throwing onError hook must not abort the flush or strand the tasks\n          // queued after it; surface it asynchronously like an unhandled task error.\n          this.scheduleMicrotask(() => {\n            throw hookError\n          })\n        }\n      } else {\n        // Surface without aborting the flush.\n        this.scheduleMicrotask(() => {\n          throw error\n        })\n      }\n    }\n  }\n\n  /**\n   * Remove an entry's dedup-key mapping, but only if the map still points at THIS\n   * entry. Keys are reused over time (a 'render' key is scheduled, runs, then\n   * scheduled again), so a stale handle or an already-dequeued entry must never\n   * evict a newer live entry's mapping — doing so would break dedup and let two\n   * same-key tasks both run.\n   */\n  private clearKey(entry: Entry): void {\n    if (entry.key !== null && this.keyed.get(entry.key) === entry) {\n      this.keyed.delete(entry.key)\n    }\n  }\n\n  private makeHandle(entry: Entry): ScheduledTask {\n    return {\n      cancel: () => {\n        entry.fn = null\n        this.clearKey(entry)\n      },\n      get pending() {\n        return entry.fn !== null\n      },\n    }\n  }\n}\n\n/** Create a new {@link Scheduler}. */\nexport function createScheduler(options?: SchedulerOptions): Scheduler {\n  return new Scheduler(options)\n}\n"],"mappings":";AA6DA,MAAM,2BACJ,OAAO,mBAAmB,aACtB,kBACC,OAAO;CACN,QAAa,QAAQ,EAAE,KAAK,EAAE;AAChC;;;;AAKN,IAAa,YAAb,MAAuB;CACrB,OAAiC,CAAC;CAClC,SAAmC,CAAC;CACpC,wBAAyB,IAAI,IAAmB;CAChD,kBAA0B;CAC1B,WAAmB;CACnB;CACA;CAEA,YAAY,SAA4B;EACtC,KAAK,UAAU,SAAS;EACxB,KAAK,oBAAoB,SAAS,qBAAqB;CACzD;;CAGA,SAAS,MAAY,SAA0C;EAC7D,MAAM,WAAW,SAAS,YAAY;EACtC,MAAM,MAAM,SAAS,OAAO;EAE5B,IAAI,QAAQ,MAAM;GAChB,MAAM,WAAW,KAAK,MAAM,IAAI,GAAG;GACnC,IAAI,YAAY,SAAS,OAAO,MAAM;IAEpC,SAAS,KAAK;IACd,OAAO,KAAK,WAAW,QAAQ;GACjC;EACF;EAEA,MAAM,QAAe;GAAE;GAAK,IAAI;EAAK;EACrC,IAAI,QAAQ,MAAM,KAAK,MAAM,IAAI,KAAK,KAAK;EAC1C,CAAC,aAAa,SAAS,KAAK,OAAO,KAAK,QAAQ,KAAK,KAAK;EAC3D,KAAK,aAAa;EAClB,OAAO,KAAK,WAAW,KAAK;CAC9B;;CAGA,YAAkB;EAChB,IAAI,KAAK,UAAU;EACnB,KAAK,WAAW;EAChB,IAAI;GAGF,OAAO,KAAK,KAAK,SAAS,KAAK,KAAK,OAAO,SAAS,GAAG;IACrD,MAAM,QAAQ,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,OAAO,MAAM;IAC3E,IAAI,CAAC,OAAO;IACZ,KAAK,SAAS,KAAK;IACnB,MAAM,KAAK,MAAM;IACjB,MAAM,KAAK;IACX,IAAI,IAAI,KAAK,IAAI,EAAE;GACrB;EACF,UAAU;GACR,KAAK,WAAW;GAChB,KAAK,kBAAkB;EACzB;CACF;;CAGA,IAAI,OAAe;EACjB,IAAI,IAAI;EACR,KAAK,MAAM,KAAK,KAAK,MAAM,IAAI,EAAE,OAAO,MAAM;EAC9C,KAAK,MAAM,KAAK,KAAK,QAAQ,IAAI,EAAE,OAAO,MAAM;EAChD,OAAO;CACT;CAEA,eAA6B;EAC3B,IAAI,KAAK,mBAAmB,KAAK,UAAU;EAC3C,KAAK,kBAAkB;EACvB,KAAK,wBAAwB;GAC3B,KAAK,kBAAkB;GACvB,KAAK,UAAU;EACjB,CAAC;CACH;CAEA,IAAY,IAAgB;EAC1B,IAAI;GACF,GAAG;EACL,SAAS,OAAO;GACd,IAAI,KAAK,SACP,IAAI;IACF,KAAK,QAAQ,KAAK;GACpB,SAAS,WAAW;IAGlB,KAAK,wBAAwB;KAC3B,MAAM;IACR,CAAC;GACH;QAGA,KAAK,wBAAwB;IAC3B,MAAM;GACR,CAAC;EAEL;CACF;;;;;;;;CASA,SAAiB,OAAoB;EACnC,IAAI,MAAM,QAAQ,QAAQ,KAAK,MAAM,IAAI,MAAM,GAAG,MAAM,OACtD,KAAK,MAAM,OAAO,MAAM,GAAG;CAE/B;CAEA,WAAmB,OAA6B;EAC9C,OAAO;GACL,cAAc;IACZ,MAAM,KAAK;IACX,KAAK,SAAS,KAAK;GACrB;GACA,IAAI,UAAU;IACZ,OAAO,MAAM,OAAO;GACtB;EACF;CACF;AACF;;AAGA,SAAgB,gBAAgB,SAAuC;CACrE,OAAO,IAAI,UAAU,OAAO;AAC9B"}

package/dist/threading/thread-pool.d.ts

@@ -0,0 +1,88 @@
+//#region src/threading/thread-pool.d.ts
+/**
+ * MindeesNative threading abstraction.
+ *
+ * Defines the **contract** for offloading CPU-bound work off the main thread, so
+ * the rest of the framework can parallelize without binding to a specific
+ * backend. Two backends are anticipated:
+ *
+ * - **Web Worker backend** (`createWorkerPool`) — works today on web; runs each
+ *   job in a `Worker`.
+ * - **Native multi-thread backend** — 🔬 research track. The interface is
+ *   defined here so the architecture is real; a native Rust-backed scheduler
+ *   will implement {@link ThreadPool} in a later phase. Until then,
+ *   {@link createInlineThreadPool} provides a correct, synchronous fallback so
+ *   callers are never blocked (Working-Code Doctrine: a real fallback, not a
+ *   lying stub).
+ *
+ * @module
+ */
+/**
+ * A pool that runs a pure job function with a transferable argument and resolves
+ * its result. Implementations may run jobs on worker threads, native threads, or
+ * (as a fallback) inline on the calling thread.
+ */
+interface ThreadPool {
+  /**
+   * Run `job(input)` and resolve its result.
+   *
+   * `job` must be a **pure, self-contained function** (it may be serialized and
+   * re-created in another realm, so it cannot close over outer variables in
+   * worker/native backends). `input` must be structured-cloneable.
+   */
+  run<In, Out>(job: (input: In) => Out, input: In): Promise<Out>;
+  /** Release all underlying resources (terminate workers, etc.). Idempotent. */
+  dispose(): void;
+  /** Number of live workers/threads (0 for the inline fallback). */
+  readonly size: number;
+}
+/**
+ * A synchronous, single-realm {@link ThreadPool}: runs each job inline on the
+ * calling thread. This is the universal fallback — correct everywhere, with no
+ * parallelism. Use it where workers aren't available (or in tests).
+ */
+declare function createInlineThreadPool(): ThreadPool;
+/** Minimal structural subset of the DOM `Worker` we depend on. */
+interface WorkerLike {
+  postMessage(message: unknown): void;
+  terminate(): void;
+  onmessage: ((event: {
+    data: unknown;
+  }) => void) | null;
+  onerror: ((event: {
+    message?: string;
+  }) => void) | null;
+}
+/** Options for {@link createWorkerPool}. */
+interface WorkerPoolOptions {
+  /** Number of workers to spawn. Defaults to 1. */
+  size?: number;
+  /**
+   * Factory that creates a worker which evaluates serialized jobs. Injectable so
+   * the pool can be unit-tested without a real `Worker` and so the host app
+   * controls how the worker module is bundled/loaded.
+   */
+  createWorker: () => WorkerLike;
+}
+/**
+ * A {@link ThreadPool} backed by Web Workers. Round-robins jobs across `size`
+ * workers. The caller supplies `createWorker`; each worker is expected to accept
+ * `{ id, source, input }` messages and reply with `{ id, ok, result }` or
+ * `{ id, ok: false, error }` (see the reference worker protocol in this package).
+ *
+ * @remarks Web-only today. The native multi-threaded backend is a research
+ * track — see the module docs.
+ */
+declare function createWorkerPool(options: WorkerPoolOptions): ThreadPool;
+/**
+ * 🔬 **Research track.** Placeholder for the native (Rust-backed) multi-threaded
+ * pool. Not implemented — throws {@link NotImplementedError}. Use
+ * {@link createWorkerPool} (web) or {@link createInlineThreadPool} (fallback)
+ * today. Tracked for a later phase.
+ *
+ * @experimental
+ */
+declare function createNativeThreadPool(): ThreadPool;
+//#endregion
+export { ThreadPool, WorkerLike, WorkerPoolOptions, createInlineThreadPool, createNativeThreadPool, createWorkerPool };
+//# sourceMappingURL=thread-pool.d.ts.map

package/dist/threading/thread-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-pool.d.ts","names":[],"sources":["../../src/threading/thread-pool.ts"],"mappings":";;AA0BA;;;;;;;;;;;;;;;;;;;;;;UAAiB,UAAA;EAYF;AAAA;AAQf;;;;AAAoD;EAZlD,GAAA,UAAa,GAAA,GAAM,KAAA,EAAO,EAAA,KAAO,GAAA,EAAK,KAAA,EAAO,EAAA,GAAK,OAAA,CAAQ,GAAA;EA+BjC;EA7BzB,OAAA;EA6ByB;EAAA,SA3BhB,IAAA;AAAA;;;;;;iBAQK,sBAAA,IAA0B,UAAU;;UAmBnC,UAAA;EACf,WAAA,CAAY,OAAA;EACZ,SAAA;EACA,SAAA,IAAa,KAAA;IAAS,IAAA;EAAA;EACtB,OAAA,IAAW,KAAA;IAAS,OAAA;EAAA;AAAA;AAYU;AAAA,UARf,iBAAA;EA2Be;EAzB9B,IAAA;EAyBsE;;;;;EAnBtE,YAAA,QAAoB,UAAU;AAAA;;;;AAqGoB;;;;;;iBAlFpC,gBAAA,CAAiB,OAAA,EAAS,iBAAA,GAAoB,UAAU;;;;;;;;;iBAkFxD,sBAAA,IAA0B,UAAU"}

package/dist/threading/thread-pool.js

@@ -0,0 +1,135 @@
+import { NotImplementedError } from "../errors.js";
+//#region src/threading/thread-pool.ts
+/**
+* MindeesNative threading abstraction.
+*
+* Defines the **contract** for offloading CPU-bound work off the main thread, so
+* the rest of the framework can parallelize without binding to a specific
+* backend. Two backends are anticipated:
+*
+* - **Web Worker backend** (`createWorkerPool`) — works today on web; runs each
+*   job in a `Worker`.
+* - **Native multi-thread backend** — 🔬 research track. The interface is
+*   defined here so the architecture is real; a native Rust-backed scheduler
+*   will implement {@link ThreadPool} in a later phase. Until then,
+*   {@link createInlineThreadPool} provides a correct, synchronous fallback so
+*   callers are never blocked (Working-Code Doctrine: a real fallback, not a
+*   lying stub).
+*
+* @module
+*/
+/**
+* A synchronous, single-realm {@link ThreadPool}: runs each job inline on the
+* calling thread. This is the universal fallback — correct everywhere, with no
+* parallelism. Use it where workers aren't available (or in tests).
+*/
+function createInlineThreadPool() {
+	let disposed = false;
+	return {
+		run(job, input) {
+			if (disposed) return Promise.reject(/* @__PURE__ */ new Error("ThreadPool is disposed"));
+			try {
+				return Promise.resolve(job(input));
+			} catch (error) {
+				return Promise.reject(error);
+			}
+		},
+		dispose() {
+			disposed = true;
+		},
+		size: 0
+	};
+}
+/**
+* A {@link ThreadPool} backed by Web Workers. Round-robins jobs across `size`
+* workers. The caller supplies `createWorker`; each worker is expected to accept
+* `{ id, source, input }` messages and reply with `{ id, ok, result }` or
+* `{ id, ok: false, error }` (see the reference worker protocol in this package).
+*
+* @remarks Web-only today. The native multi-threaded backend is a research
+* track — see the module docs.
+*/
+function createWorkerPool(options) {
+	const count = Math.max(1, options.size ?? 1);
+	const workers = [];
+	const pending = /* @__PURE__ */ new Map();
+	let nextId = 0;
+	let rr = 0;
+	let disposed = false;
+	/** Reject and forget every in-flight job dispatched to a given worker. */
+	function rejectWorkerJobs(workerIndex, message) {
+		for (const [id, job] of pending) if (job.workerIndex === workerIndex) {
+			pending.delete(id);
+			job.reject(new Error(message));
+		}
+	}
+	/** Create a worker at `index`, wire its handlers, and store it in place. */
+	function spawn(index) {
+		const w = options.createWorker();
+		w.onmessage = (event) => {
+			const data = event.data;
+			const job = pending.get(data.id);
+			if (!job) return;
+			pending.delete(data.id);
+			if (data.ok) job.resolve(data.result);
+			else job.reject(new Error(data.error ?? "worker job failed"));
+		};
+		w.onerror = (event) => {
+			if (disposed) return;
+			rejectWorkerJobs(index, event.message ?? "worker error");
+			try {
+				w.terminate();
+			} catch {}
+			spawn(index);
+		};
+		workers[index] = w;
+	}
+	for (let i = 0; i < count; i++) spawn(i);
+	return {
+		run(job, input) {
+			if (disposed) return Promise.reject(/* @__PURE__ */ new Error("ThreadPool is disposed"));
+			const index = rr % workers.length;
+			rr++;
+			const worker = workers[index];
+			if (!worker) return Promise.reject(/* @__PURE__ */ new Error("no worker available"));
+			const id = nextId++;
+			return new Promise((resolve, reject) => {
+				pending.set(id, {
+					resolve,
+					reject,
+					workerIndex: index
+				});
+				worker.postMessage({
+					id,
+					source: job.toString(),
+					input
+				});
+			});
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			for (const w of workers) w.terminate();
+			for (const [, job] of pending) job.reject(/* @__PURE__ */ new Error("ThreadPool disposed"));
+			pending.clear();
+		},
+		get size() {
+			return disposed ? 0 : workers.length;
+		}
+	};
+}
+/**
+* 🔬 **Research track.** Placeholder for the native (Rust-backed) multi-threaded
+* pool. Not implemented — throws {@link NotImplementedError}. Use
+* {@link createWorkerPool} (web) or {@link createInlineThreadPool} (fallback)
+* today. Tracked for a later phase.
+*
+* @experimental
+*/
+function createNativeThreadPool() {
+	throw new NotImplementedError("Native multi-threaded ThreadPool");
+}
+//#endregion
+export { createInlineThreadPool, createNativeThreadPool, createWorkerPool };
+
+//# sourceMappingURL=thread-pool.js.map

package/dist/threading/thread-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-pool.js","names":[],"sources":["../../src/threading/thread-pool.ts"],"sourcesContent":["/**\n * MindeesNative threading abstraction.\n *\n * Defines the **contract** for offloading CPU-bound work off the main thread, so\n * the rest of the framework can parallelize without binding to a specific\n * backend. Two backends are anticipated:\n *\n * - **Web Worker backend** (`createWorkerPool`) — works today on web; runs each\n *   job in a `Worker`.\n * - **Native multi-thread backend** — 🔬 research track. The interface is\n *   defined here so the architecture is real; a native Rust-backed scheduler\n *   will implement {@link ThreadPool} in a later phase. Until then,\n *   {@link createInlineThreadPool} provides a correct, synchronous fallback so\n *   callers are never blocked (Working-Code Doctrine: a real fallback, not a\n *   lying stub).\n *\n * @module\n */\n\nimport { NotImplementedError } from '../errors'\n\n/**\n * A pool that runs a pure job function with a transferable argument and resolves\n * its result. Implementations may run jobs on worker threads, native threads, or\n * (as a fallback) inline on the calling thread.\n */\nexport interface ThreadPool {\n  /**\n   * Run `job(input)` and resolve its result.\n   *\n   * `job` must be a **pure, self-contained function** (it may be serialized and\n   * re-created in another realm, so it cannot close over outer variables in\n   * worker/native backends). `input` must be structured-cloneable.\n   */\n  run<In, Out>(job: (input: In) => Out, input: In): Promise<Out>\n  /** Release all underlying resources (terminate workers, etc.). Idempotent. */\n  dispose(): void\n  /** Number of live workers/threads (0 for the inline fallback). */\n  readonly size: number\n}\n\n/**\n * A synchronous, single-realm {@link ThreadPool}: runs each job inline on the\n * calling thread. This is the universal fallback — correct everywhere, with no\n * parallelism. Use it where workers aren't available (or in tests).\n */\nexport function createInlineThreadPool(): ThreadPool {\n  let disposed = false\n  return {\n    run<In, Out>(job: (input: In) => Out, input: In): Promise<Out> {\n      if (disposed) return Promise.reject(new Error('ThreadPool is disposed'))\n      try {\n        return Promise.resolve(job(input))\n      } catch (error) {\n        return Promise.reject(error as Error)\n      }\n    },\n    dispose() {\n      disposed = true\n    },\n    size: 0,\n  }\n}\n\n/** Minimal structural subset of the DOM `Worker` we depend on. */\nexport interface WorkerLike {\n  postMessage(message: unknown): void\n  terminate(): void\n  onmessage: ((event: { data: unknown }) => void) | null\n  onerror: ((event: { message?: string }) => void) | null\n}\n\n/** Options for {@link createWorkerPool}. */\nexport interface WorkerPoolOptions {\n  /** Number of workers to spawn. Defaults to 1. */\n  size?: number\n  /**\n   * Factory that creates a worker which evaluates serialized jobs. Injectable so\n   * the pool can be unit-tested without a real `Worker` and so the host app\n   * controls how the worker module is bundled/loaded.\n   */\n  createWorker: () => WorkerLike\n}\n\ninterface PendingJob {\n  resolve: (value: unknown) => void\n  reject: (error: unknown) => void\n  /** Index of the worker this job was dispatched to (for crash correlation). */\n  workerIndex: number\n}\n\n/**\n * A {@link ThreadPool} backed by Web Workers. Round-robins jobs across `size`\n * workers. The caller supplies `createWorker`; each worker is expected to accept\n * `{ id, source, input }` messages and reply with `{ id, ok, result }` or\n * `{ id, ok: false, error }` (see the reference worker protocol in this package).\n *\n * @remarks Web-only today. The native multi-threaded backend is a research\n * track — see the module docs.\n */\nexport function createWorkerPool(options: WorkerPoolOptions): ThreadPool {\n  const count = Math.max(1, options.size ?? 1)\n  const workers: WorkerLike[] = []\n  const pending = new Map<number, PendingJob>()\n  let nextId = 0\n  let rr = 0\n  let disposed = false\n\n  /** Reject and forget every in-flight job dispatched to a given worker. */\n  function rejectWorkerJobs(workerIndex: number, message: string): void {\n    for (const [id, job] of pending) {\n      if (job.workerIndex === workerIndex) {\n        pending.delete(id)\n        job.reject(new Error(message))\n      }\n    }\n  }\n\n  /** Create a worker at `index`, wire its handlers, and store it in place. */\n  function spawn(index: number): void {\n    const w = options.createWorker()\n    w.onmessage = (event) => {\n      const data = event.data as { id: number; ok: boolean; result?: unknown; error?: string }\n      const job = pending.get(data.id)\n      if (!job) return\n      pending.delete(data.id)\n      if (data.ok) job.resolve(data.result)\n      else job.reject(new Error(data.error ?? 'worker job failed'))\n    }\n    w.onerror = (event) => {\n      if (disposed) return\n      // A worker crash loses EVERY job in flight on it (a worker can carry many\n      // concurrently). Reject all of them — correlated by worker index, so a\n      // healthy worker's jobs are never touched — then replace the dead worker in\n      // place so the pool stays live and `size` keeps reflecting reality.\n      rejectWorkerJobs(index, event.message ?? 'worker error')\n      try {\n        w.terminate()\n      } catch {\n        // The worker is already dead; ignore terminate failures.\n      }\n      spawn(index)\n    }\n    workers[index] = w\n  }\n\n  for (let i = 0; i < count; i++) spawn(i)\n\n  return {\n    run<In, Out>(job: (input: In) => Out, input: In): Promise<Out> {\n      if (disposed) return Promise.reject(new Error('ThreadPool is disposed'))\n      const index = rr % workers.length\n      rr++\n      const worker = workers[index]\n      if (!worker) return Promise.reject(new Error('no worker available'))\n      const id = nextId++\n      return new Promise<Out>((resolve, reject) => {\n        pending.set(id, { resolve: resolve as (v: unknown) => void, reject, workerIndex: index })\n        worker.postMessage({ id, source: job.toString(), input })\n      })\n    },\n    dispose() {\n      if (disposed) return\n      disposed = true\n      for (const w of workers) w.terminate()\n      for (const [, job] of pending) job.reject(new Error('ThreadPool disposed'))\n      pending.clear()\n    },\n    get size() {\n      return disposed ? 0 : workers.length\n    },\n  }\n}\n\n/**\n * 🔬 **Research track.** Placeholder for the native (Rust-backed) multi-threaded\n * pool. Not implemented — throws {@link NotImplementedError}. Use\n * {@link createWorkerPool} (web) or {@link createInlineThreadPool} (fallback)\n * today. Tracked for a later phase.\n *\n * @experimental\n */\nexport function createNativeThreadPool(): ThreadPool {\n  throw new NotImplementedError('Native multi-threaded ThreadPool')\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,SAAgB,yBAAqC;CACnD,IAAI,WAAW;CACf,OAAO;EACL,IAAa,KAAyB,OAAyB;GAC7D,IAAI,UAAU,OAAO,QAAQ,uBAAO,IAAI,MAAM,wBAAwB,CAAC;GACvE,IAAI;IACF,OAAO,QAAQ,QAAQ,IAAI,KAAK,CAAC;GACnC,SAAS,OAAO;IACd,OAAO,QAAQ,OAAO,KAAc;GACtC;EACF;EACA,UAAU;GACR,WAAW;EACb;EACA,MAAM;CACR;AACF;;;;;;;;;;AAsCA,SAAgB,iBAAiB,SAAwC;CACvE,MAAM,QAAQ,KAAK,IAAI,GAAG,QAAQ,QAAQ,CAAC;CAC3C,MAAM,UAAwB,CAAC;CAC/B,MAAM,0BAAU,IAAI,IAAwB;CAC5C,IAAI,SAAS;CACb,IAAI,KAAK;CACT,IAAI,WAAW;;CAGf,SAAS,iBAAiB,aAAqB,SAAuB;EACpE,KAAK,MAAM,CAAC,IAAI,QAAQ,SACtB,IAAI,IAAI,gBAAgB,aAAa;GACnC,QAAQ,OAAO,EAAE;GACjB,IAAI,OAAO,IAAI,MAAM,OAAO,CAAC;EAC/B;CAEJ;;CAGA,SAAS,MAAM,OAAqB;EAClC,MAAM,IAAI,QAAQ,aAAa;EAC/B,EAAE,aAAa,UAAU;GACvB,MAAM,OAAO,MAAM;GACnB,MAAM,MAAM,QAAQ,IAAI,KAAK,EAAE;GAC/B,IAAI,CAAC,KAAK;GACV,QAAQ,OAAO,KAAK,EAAE;GACtB,IAAI,KAAK,IAAI,IAAI,QAAQ,KAAK,MAAM;QAC/B,IAAI,OAAO,IAAI,MAAM,KAAK,SAAS,mBAAmB,CAAC;EAC9D;EACA,EAAE,WAAW,UAAU;GACrB,IAAI,UAAU;GAKd,iBAAiB,OAAO,MAAM,WAAW,cAAc;GACvD,IAAI;IACF,EAAE,UAAU;GACd,QAAQ,CAER;GACA,MAAM,KAAK;EACb;EACA,QAAQ,SAAS;CACnB;CAEA,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,KAAK,MAAM,CAAC;CAEvC,OAAO;EACL,IAAa,KAAyB,OAAyB;GAC7D,IAAI,UAAU,OAAO,QAAQ,uBAAO,IAAI,MAAM,wBAAwB,CAAC;GACvE,MAAM,QAAQ,KAAK,QAAQ;GAC3B;GACA,MAAM,SAAS,QAAQ;GACvB,IAAI,CAAC,QAAQ,OAAO,QAAQ,uBAAO,IAAI,MAAM,qBAAqB,CAAC;GACnE,MAAM,KAAK;GACX,OAAO,IAAI,SAAc,SAAS,WAAW;IAC3C,QAAQ,IAAI,IAAI;KAAW;KAAiC;KAAQ,aAAa;IAAM,CAAC;IACxF,OAAO,YAAY;KAAE;KAAI,QAAQ,IAAI,SAAS;KAAG;IAAM,CAAC;GAC1D,CAAC;EACH;EACA,UAAU;GACR,IAAI,UAAU;GACd,WAAW;GACX,KAAK,MAAM,KAAK,SAAS,EAAE,UAAU;GACrC,KAAK,MAAM,GAAG,QAAQ,SAAS,IAAI,uBAAO,IAAI,MAAM,qBAAqB,CAAC;GAC1E,QAAQ,MAAM;EAChB;EACA,IAAI,OAAO;GACT,OAAO,WAAW,IAAI,QAAQ;EAChC;CACF;AACF;;;;;;;;;AAUA,SAAgB,yBAAqC;CACnD,MAAM,IAAI,oBAAoB,kCAAkC;AAClE"}

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+//#region src/types.d.ts
+/**
+ * Maturity level of a MindeesNative package or capability.
+ *
+ * Mirrors the legend in the repository `STATUS.md`. Used so tooling and
+ * consumers can introspect, honestly, how finished a piece of the framework is.
+ */
+type Maturity = 'stable' | 'experimental' | 'research-track' | 'planned' | 'scaffold';
+/**
+ * Static identity + maturity metadata exported by every `@mindees/*` package.
+ */
+interface PackageInfo {
+  /** The npm package name, e.g. `@mindees/core`. */
+  readonly name: string;
+  /** The package version. All `@mindees/*` packages share one locked version line. */
+  readonly version: string;
+  /** Current maturity of the package. */
+  readonly maturity: Maturity;
+}
+//#endregion
+export { Maturity, PackageInfo };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;AAMA;;;;AAAoB;KAAR,QAAA;;;;UAKK,WAAA;EAIN;EAAA,SAFA,IAAA;EAIU;EAAA,SAFV,OAAA;EAEkB;EAAA,SAAlB,QAAA,EAAU,QAAQ;AAAA"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mindees/core",
+  "version": "0.1.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",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mindees/mindees.git",
+    "directory": "packages/core"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}