@orkestrel/workflow 0.0.1

package/dist/src/browser/index.js

@@ -0,0 +1,399 @@
+import { isFunction, isRecord } from "@orkestrel/contract";
+//#region src/browser/constants.ts
+/**
+* The browser-native `postTask` priority for each portable {@link SchedulerPriority} — the
+* Prioritized Task Scheduling API's three levels.
+*
+* @remarks
+* A `user` hint maps to the most urgent `'user-blocking'`, `normal` to the default
+* `'user-visible'`, and `background` to `'background'`. {@link BrowserScheduler} reads this
+* map to translate the caller's portable priority into the value passed to
+* `scheduler.postTask`, so the urgency hint is honoured by the host.
+*/
+var POST_TASK_PRIORITY = {
+	user: "user-blocking",
+	normal: "user-visible",
+	background: "background"
+};
+//#endregion
+//#region src/browser/BrowserScheduler.ts
+/**
+* The browser {@link SchedulerInterface} — the browser-native cooperative-yield backend
+* built on the Prioritized Task Scheduling API (`scheduler.postTask`), falling back to a
+* zero-delay macrotask where it is absent.
+*
+* @remarks
+* - **`yield` prefers `scheduler.postTask`, honouring priority.** When `globalThis`
+*   exposes a `scheduler` with a `postTask` method, `yield()` posts a task at the mapped
+*   priority (`user` → `'user-blocking'`, `normal` → `'user-visible'`, `background` →
+*   `'background'`), so the host genuinely regains control and the urgency hint is
+*   honoured. The capability is feature-detected through guards (`isRecord` / `isFunction`),
+*   never an `as` (AGENTS §14). Where the API is absent (Firefox today, older engines),
+*   it **falls back** to a `setTimeout(0)` macrotask — still a real host-turn, just
+*   without priority. `delay(ms)` is always a real `setTimeout`.
+* - **Abort fidelity is verbatim.** A pending `yield` / `delay` rejects with `signal.reason`
+*   exactly — the value the caller passed, never wrapped or replaced. The discipline
+*   mirrors the cross-environment default's `#sleep`: an already-aborted signal rejects
+*   immediately WITHOUT scheduling; otherwise the host-turn is scheduled and a
+*   `{ once: true }` abort listener attached, and the two settle paths are mutually
+*   exclusive — the turn path removes the listener before resolving, and the abort path
+*   cancels the scheduled turn before rejecting. The promise settles exactly once, with no
+*   leaked task/timer and no leaked listener. The caller's `signal` is NOT handed to
+*   `postTask` (whose own abort would reject with a platform `AbortError`, not the
+*   caller's `reason`); instead an internal controller cancels the posted task while this
+*   scheduler rejects with the verbatim `signal.reason`.
+* - **Event-free.** A pure functional primitive — no Emitter, no events.
+*
+* @example
+* ```ts
+* import { createAbort } from '@src/core'
+* import { BrowserScheduler } from '@src/browser'
+*
+* const abort = createAbort()
+* const scheduler = new BrowserScheduler()
+* while (!abort.signal.aborted) {
+* 	doSomeWork()
+* 	await scheduler.yield({ priority: 'background', signal: abort.signal })
+* }
+* ```
+*/
+var BrowserScheduler = class {
+	/**
+	* Yield control to the host via `scheduler.postTask` at the given priority (or a
+	* `setTimeout(0)` macrotask where the API is absent), then resume; abort rejects with
+	* `signal.reason`.
+	*/
+	yield(options) {
+		const post = this.#postTask();
+		if (post === void 0) return this.#macrotask(options?.signal);
+		return this.#yieldVia(post, options?.priority ?? "normal", options?.signal);
+	}
+	/**
+	* Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with
+	* `signal.reason`.
+	*
+	* @remarks
+	* `ms` should be a non-negative finite number. The primitive does no validation: it
+	* passes `ms` straight to the host `setTimeout`, which clamps a negative value or
+	* `NaN` to ~0 — so an out-of-domain `ms` resolves on the next host turn rather than
+	* throwing.
+	*/
+	delay(ms, options) {
+		return this.#timer(ms, options?.signal);
+	}
+	#postTask() {
+		const candidate = Reflect.get(globalThis, "scheduler");
+		if (!isRecord(candidate)) return void 0;
+		const post = candidate.postTask;
+		if (!isFunction(post)) return void 0;
+		return (callback, options) => Reflect.apply(post, candidate, [callback, options]);
+	}
+	#yieldVia(post, priority, signal) {
+		if (signal?.aborted === true) return Promise.reject(signal.reason);
+		return new Promise((resolve, reject) => {
+			const internal = new AbortController();
+			const onAbort = () => {
+				internal.abort();
+				reject(signal?.reason);
+			};
+			const task = post(() => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve();
+			}, {
+				priority: POST_TASK_PRIORITY[priority],
+				signal: internal.signal
+			});
+			if (task instanceof Promise) task.catch(() => {});
+			signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+	#macrotask(signal) {
+		return this.#timer(0, signal);
+	}
+	#timer(ms, signal) {
+		if (signal?.aborted === true) return Promise.reject(signal.reason);
+		return new Promise((resolve, reject) => {
+			const onAbort = () => {
+				clearTimeout(handle);
+				reject(signal?.reason);
+			};
+			const handle = setTimeout(() => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve();
+			}, ms);
+			signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+};
+//#endregion
+//#region src/browser/FrameScheduler.ts
+/**
+* The frame-aligned {@link SchedulerInterface} — a browser cooperative-yield backend
+* whose `yield` resumes just before the next paint via `requestAnimationFrame`.
+*
+* @remarks
+* - **`yield` resumes before the next paint.** `yield()` waits on `requestAnimationFrame`,
+*   so the resumption is aligned to the browser's render loop — ideal for work that
+*   should batch per frame (animation, incremental DOM updates) and pause while the tab
+*   is hidden (the host throttles rAF). `delay(ms)` is a real `setTimeout`, unaligned to
+*   frames. `options.priority` is accepted for contract compliance but a no-op — a frame
+*   callback has no priority dimension.
+* - **Abort fidelity is verbatim, with cleanup.** A pending `yield` / `delay` rejects with
+*   `signal.reason` exactly. The discipline mirrors the cross-environment default's
+*   `#sleep`: an already-aborted signal rejects immediately WITHOUT scheduling a frame;
+*   otherwise the frame is requested and a `{ once: true }` abort listener attached, and
+*   the two settle paths are mutually exclusive — the frame path removes the listener
+*   before resolving, and the abort path `cancelAnimationFrame`s the pending handle before
+*   rejecting. The promise settles exactly once, with no leaked frame request and no
+*   leaked listener.
+* - **Event-free.** A pure functional primitive — no Emitter, no events.
+*
+* @example
+* ```ts
+* import { createAbort } from '@src/core'
+* import { FrameScheduler } from '@src/browser'
+*
+* const abort = createAbort()
+* const scheduler = new FrameScheduler()
+* while (!abort.signal.aborted) {
+* 	renderOneFrameOfWork()
+* 	await scheduler.yield({ signal: abort.signal }) // resume before the next paint
+* }
+* ```
+*/
+var FrameScheduler = class {
+	/**
+	* Yield control to the host until just before the next paint via
+	* `requestAnimationFrame`, then resume; abort rejects with `signal.reason`.
+	*/
+	yield(options) {
+		return this.#frame(options?.signal);
+	}
+	/**
+	* Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with
+	* `signal.reason`.
+	*
+	* @remarks
+	* `ms` should be a non-negative finite number. The primitive does no validation: it
+	* passes `ms` straight to the host `setTimeout`, which clamps a negative value or
+	* `NaN` to ~0 — so an out-of-domain `ms` resolves on the next host turn rather than
+	* throwing.
+	*/
+	delay(ms, options) {
+		return this.#sleep(ms, options?.signal);
+	}
+	#frame(signal) {
+		if (signal?.aborted === true) return Promise.reject(signal.reason);
+		return new Promise((resolve, reject) => {
+			const onAbort = () => {
+				cancelAnimationFrame(handle);
+				reject(signal?.reason);
+			};
+			const handle = requestAnimationFrame(() => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve();
+			});
+			signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+	#sleep(ms, signal) {
+		if (signal?.aborted === true) return Promise.reject(signal.reason);
+		return new Promise((resolve, reject) => {
+			const onAbort = () => {
+				clearTimeout(handle);
+				reject(signal?.reason);
+			};
+			const handle = setTimeout(() => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve();
+			}, ms);
+			signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+};
+//#endregion
+//#region src/browser/IdleScheduler.ts
+/**
+* The idle-time {@link SchedulerInterface} — a browser cooperative-yield backend whose
+* `yield` resumes when the host is idle via `requestIdleCallback`, falling back to a
+* zero-delay macrotask where it is absent.
+*
+* @remarks
+* - **`yield` resumes during idle time.** When `globalThis` exposes `requestIdleCallback`,
+*   `yield()` waits on it, so the resumption happens when the browser has spare time after
+*   rendering and input — ideal for low-priority background work that must not contend with
+*   the user. The capability is feature-detected through a guard (`isFunction`), never an
+*   `as` (AGENTS §14). Where the API is absent (Safari today), it **falls back** to a
+*   `setTimeout(0)` macrotask — still a real host-turn, just not idle-gated. `delay(ms)` is
+*   always a real `setTimeout`. `options.priority` is accepted for contract compliance but a
+*   no-op — idle scheduling has no priority dimension.
+* - **Abort fidelity is verbatim, with cleanup.** A pending `yield` / `delay` rejects with
+*   `signal.reason` exactly. The discipline mirrors the cross-environment default's
+*   `#sleep`: an already-aborted signal rejects immediately WITHOUT scheduling; otherwise
+*   the idle callback (or fallback timer) is requested and a `{ once: true }` abort listener
+*   attached, and the two settle paths are mutually exclusive — the resume path removes the
+*   listener before resolving, and the abort path `cancelIdleCallback`s (or `clearTimeout`s)
+*   the pending handle before rejecting. The promise settles exactly once, with no leaked
+*   callback/timer and no leaked listener.
+* - **Event-free.** A pure functional primitive — no Emitter, no events.
+*
+* @example
+* ```ts
+* import { createAbort } from '@src/core'
+* import { IdleScheduler } from '@src/browser'
+*
+* const abort = createAbort()
+* const scheduler = new IdleScheduler()
+* while (!abort.signal.aborted) {
+* 	doLowPriorityWork()
+* 	await scheduler.yield({ signal: abort.signal }) // resume when the host is idle
+* }
+* ```
+*/
+var IdleScheduler = class {
+	/**
+	* Yield control to the host until it is idle via `requestIdleCallback` (or a
+	* `setTimeout(0)` macrotask where the API is absent), then resume; abort rejects with
+	* `signal.reason`.
+	*/
+	yield(options) {
+		const idle = this.#idleAPI();
+		if (idle === void 0) return this.#sleep(0, options?.signal);
+		return this.#idle(idle, options?.signal);
+	}
+	/**
+	* Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with
+	* `signal.reason`.
+	*
+	* @remarks
+	* `ms` should be a non-negative finite number. The primitive does no validation: it
+	* passes `ms` straight to the host `setTimeout`, which clamps a negative value or
+	* `NaN` to ~0 — so an out-of-domain `ms` resolves on the next host turn rather than
+	* throwing.
+	*/
+	delay(ms, options) {
+		return this.#sleep(ms, options?.signal);
+	}
+	#idleAPI() {
+		const request = Reflect.get(globalThis, "requestIdleCallback");
+		const cancel = Reflect.get(globalThis, "cancelIdleCallback");
+		if (!isFunction(request) || !isFunction(cancel)) return void 0;
+		return {
+			request: (callback) => Number(Reflect.apply(request, globalThis, [callback])),
+			cancel: (handle) => {
+				Reflect.apply(cancel, globalThis, [handle]);
+			}
+		};
+	}
+	#idle(idle, signal) {
+		if (signal?.aborted === true) return Promise.reject(signal.reason);
+		return new Promise((resolve, reject) => {
+			const onAbort = () => {
+				idle.cancel(handle);
+				reject(signal?.reason);
+			};
+			const handle = idle.request(() => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve();
+			});
+			signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+	#sleep(ms, signal) {
+		if (signal?.aborted === true) return Promise.reject(signal.reason);
+		return new Promise((resolve, reject) => {
+			const onAbort = () => {
+				clearTimeout(handle);
+				reject(signal?.reason);
+			};
+			const handle = setTimeout(() => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve();
+			}, ms);
+			signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+};
+//#endregion
+//#region src/browser/factories.ts
+/**
+* Create the browser-native cooperative-yield {@link SchedulerInterface} — `yield()` uses
+* the Prioritized Task Scheduling API (`scheduler.postTask`) at the requested priority
+* when present, falling back to a `setTimeout(0)` macrotask; `delay(ms)` is a real
+* `setTimeout`.
+*
+* @remarks
+* The default browser scheduler: it honours `options.priority` (`user` /
+* `normal` / `background`) when `scheduler.postTask` is available and degrades to a plain
+* macrotask elsewhere. Both methods are abort-aware: pass `options.signal` and a pending
+* yield/delay rejects with the signal's `reason` verbatim, with full task/timer/listener
+* cleanup. Prefer {@link createFrameScheduler} for paint-aligned work or
+* {@link createIdleScheduler} for idle-time background work.
+*
+* @returns A {@link SchedulerInterface} backed by `scheduler.postTask` (or a macrotask)
+*
+* @example
+* ```ts
+* import { createBrowserScheduler } from '@src/browser'
+*
+* const scheduler = createBrowserScheduler()
+* await scheduler.yield({ priority: 'background' })
+* ```
+*/
+function createBrowserScheduler() {
+	return new BrowserScheduler();
+}
+/**
+* Create the frame-aligned cooperative-yield {@link SchedulerInterface} — `yield()` resumes
+* just before the next paint via `requestAnimationFrame`; `delay(ms)` is a real
+* `setTimeout`.
+*
+* @remarks
+* Use it for work that should batch per render frame (animation, incremental DOM updates)
+* and naturally pause while the tab is hidden. `yield` is abort-aware: pass `options.signal`
+* and a pending yield rejects with the signal's `reason` verbatim, cancelling the pending
+* frame request. `options.priority` is accepted but a no-op — a frame callback has no
+* priority dimension.
+*
+* @returns A {@link SchedulerInterface} backed by `requestAnimationFrame`
+*
+* @example
+* ```ts
+* import { createFrameScheduler } from '@src/browser'
+*
+* const scheduler = createFrameScheduler()
+* await scheduler.yield() // resumes before the next paint
+* ```
+*/
+function createFrameScheduler() {
+	return new FrameScheduler();
+}
+/**
+* Create the idle-time cooperative-yield {@link SchedulerInterface} — `yield()` resumes when
+* the host is idle via `requestIdleCallback` when present, falling back to a `setTimeout(0)`
+* macrotask; `delay(ms)` is a real `setTimeout`.
+*
+* @remarks
+* Use it for low-priority background work that must not contend with rendering or input.
+* Where `requestIdleCallback` is absent (Safari today) it degrades to a plain macrotask.
+* `yield` is abort-aware: pass `options.signal` and a pending yield rejects with the
+* signal's `reason` verbatim, cancelling the pending idle callback. `options.priority` is
+* accepted but a no-op — idle scheduling has no priority dimension.
+*
+* @returns A {@link SchedulerInterface} backed by `requestIdleCallback` (or a macrotask)
+*
+* @example
+* ```ts
+* import { createIdleScheduler } from '@src/browser'
+*
+* const scheduler = createIdleScheduler()
+* await scheduler.yield() // resumes when the host is idle
+* ```
+*/
+function createIdleScheduler() {
+	return new IdleScheduler();
+}
+//#endregion
+export { BrowserScheduler, FrameScheduler, IdleScheduler, POST_TASK_PRIORITY, createBrowserScheduler, createFrameScheduler, createIdleScheduler };
+
+//# sourceMappingURL=index.js.map

package/dist/src/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#postTask","#macrotask","#yieldVia","#timer","#frame","#sleep","#idleAPI","#sleep","#idle"],"sources":["../../../src/browser/constants.ts","../../../src/browser/BrowserScheduler.ts","../../../src/browser/FrameScheduler.ts","../../../src/browser/IdleScheduler.ts","../../../src/browser/factories.ts"],"sourcesContent":["import type { SchedulerPriority } from '@src/core'\n\n/**\n * The browser-native `postTask` priority for each portable {@link SchedulerPriority} — the\n * Prioritized Task Scheduling API's three levels.\n *\n * @remarks\n * A `user` hint maps to the most urgent `'user-blocking'`, `normal` to the default\n * `'user-visible'`, and `background` to `'background'`. {@link BrowserScheduler} reads this\n * map to translate the caller's portable priority into the value passed to\n * `scheduler.postTask`, so the urgency hint is honoured by the host.\n */\nexport const POST_TASK_PRIORITY: Readonly<Record<SchedulerPriority, string>> = {\n\tuser: 'user-blocking',\n\tnormal: 'user-visible',\n\tbackground: 'background',\n}\n","import type { SchedulerInterface, SchedulerOptions, SchedulerPriority } from '@src/core'\nimport { isFunction, isRecord } from '@orkestrel/contract'\nimport { POST_TASK_PRIORITY } from './constants.js'\n\n/**\n * The browser {@link SchedulerInterface} — the browser-native cooperative-yield backend\n * built on the Prioritized Task Scheduling API (`scheduler.postTask`), falling back to a\n * zero-delay macrotask where it is absent.\n *\n * @remarks\n * - **`yield` prefers `scheduler.postTask`, honouring priority.** When `globalThis`\n *   exposes a `scheduler` with a `postTask` method, `yield()` posts a task at the mapped\n *   priority (`user` → `'user-blocking'`, `normal` → `'user-visible'`, `background` →\n *   `'background'`), so the host genuinely regains control and the urgency hint is\n *   honoured. The capability is feature-detected through guards (`isRecord` / `isFunction`),\n *   never an `as` (AGENTS §14). Where the API is absent (Firefox today, older engines),\n *   it **falls back** to a `setTimeout(0)` macrotask — still a real host-turn, just\n *   without priority. `delay(ms)` is always a real `setTimeout`.\n * - **Abort fidelity is verbatim.** A pending `yield` / `delay` rejects with `signal.reason`\n *   exactly — the value the caller passed, never wrapped or replaced. The discipline\n *   mirrors the cross-environment default's `#sleep`: an already-aborted signal rejects\n *   immediately WITHOUT scheduling; otherwise the host-turn is scheduled and a\n *   `{ once: true }` abort listener attached, and the two settle paths are mutually\n *   exclusive — the turn path removes the listener before resolving, and the abort path\n *   cancels the scheduled turn before rejecting. The promise settles exactly once, with no\n *   leaked task/timer and no leaked listener. The caller's `signal` is NOT handed to\n *   `postTask` (whose own abort would reject with a platform `AbortError`, not the\n *   caller's `reason`); instead an internal controller cancels the posted task while this\n *   scheduler rejects with the verbatim `signal.reason`.\n * - **Event-free.** A pure functional primitive — no Emitter, no events.\n *\n * @example\n * ```ts\n * import { createAbort } from '@src/core'\n * import { BrowserScheduler } from '@src/browser'\n *\n * const abort = createAbort()\n * const scheduler = new BrowserScheduler()\n * while (!abort.signal.aborted) {\n * \tdoSomeWork()\n * \tawait scheduler.yield({ priority: 'background', signal: abort.signal })\n * }\n * ```\n */\nexport class BrowserScheduler implements SchedulerInterface {\n\t/**\n\t * Yield control to the host via `scheduler.postTask` at the given priority (or a\n\t * `setTimeout(0)` macrotask where the API is absent), then resume; abort rejects with\n\t * `signal.reason`.\n\t */\n\tyield(options?: SchedulerOptions): Promise<void> {\n\t\tconst post = this.#postTask()\n\t\tif (post === undefined) return this.#macrotask(options?.signal)\n\t\treturn this.#yieldVia(post, options?.priority ?? 'normal', options?.signal)\n\t}\n\n\t/**\n\t * Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with\n\t * `signal.reason`.\n\t *\n\t * @remarks\n\t * `ms` should be a non-negative finite number. The primitive does no validation: it\n\t * passes `ms` straight to the host `setTimeout`, which clamps a negative value or\n\t * `NaN` to ~0 — so an out-of-domain `ms` resolves on the next host turn rather than\n\t * throwing.\n\t */\n\tdelay(ms: number, options?: SchedulerOptions): Promise<void> {\n\t\treturn this.#timer(ms, options?.signal)\n\t}\n\n\t// === Private\n\n\t// Feature-detect the Prioritized Task Scheduling API through guards (no `as`): the\n\t// global `scheduler` must be a record carrying a callable `postTask`. Returns the\n\t// narrowed `postTask` function, or `undefined` when the API is absent (the fallback).\n\t#postTask(): ((callback: () => void, options: Record<string, unknown>) => unknown) | undefined {\n\t\tconst candidate: unknown = Reflect.get(globalThis, 'scheduler')\n\t\tif (!isRecord(candidate)) return undefined\n\t\tconst post = candidate.postTask\n\t\tif (!isFunction(post)) return undefined\n\t\treturn (callback, options) => Reflect.apply(post, candidate, [callback, options])\n\t}\n\n\t// A `scheduler.postTask` host-turn at the mapped priority. The caller's signal is NOT\n\t// passed to `postTask` (its abort rejects with a platform `AbortError`, not the\n\t// caller's `reason`); instead an internal controller cancels the posted task on abort\n\t// while this rejects with the verbatim `signal.reason`. Settle-once, no leak: the task\n\t// path removes the abort listener before resolving; the abort path aborts the internal\n\t// controller (cancelling the task) before rejecting.\n\t#yieldVia(\n\t\tpost: (callback: () => void, options: Record<string, unknown>) => unknown,\n\t\tpriority: SchedulerPriority,\n\t\tsignal?: AbortSignal,\n\t): Promise<void> {\n\t\tif (signal?.aborted === true) return Promise.reject(signal.reason)\n\t\treturn new Promise<void>((resolve, reject) => {\n\t\t\tconst internal = new AbortController()\n\t\t\tconst onAbort = () => {\n\t\t\t\tinternal.abort()\n\t\t\t\treject(signal?.reason)\n\t\t\t}\n\t\t\tconst task = post(\n\t\t\t\t() => {\n\t\t\t\t\tsignal?.removeEventListener('abort', onAbort)\n\t\t\t\t\tresolve()\n\t\t\t\t},\n\t\t\t\t{ priority: POST_TASK_PRIORITY[priority], signal: internal.signal },\n\t\t\t)\n\t\t\t// `postTask` returns a promise that rejects when the internal controller aborts;\n\t\t\t// swallow that rejection (the abort path already rejected with the real reason).\n\t\t\tif (task instanceof Promise) task.catch(() => {})\n\t\t\tsignal?.addEventListener('abort', onAbort, { once: true })\n\t\t})\n\t}\n\n\t// The `setTimeout(0)` macrotask fallback for `yield` when `postTask` is absent. Same\n\t// settle-once discipline as the core `#sleep`: an already-aborted signal rejects\n\t// without arming; otherwise the timer path removes the listener before resolving and\n\t// the abort path clears the timer before rejecting with `signal.reason`.\n\t#macrotask(signal?: AbortSignal): Promise<void> {\n\t\treturn this.#timer(0, signal)\n\t}\n\n\t// The abort-aware `setTimeout` sleep shared by `delay` and the `yield` macrotask\n\t// fallback. Settle-once, no leak (the core `#sleep` discipline): already-aborted →\n\t// reject without arming; the timer path removes the listener before resolving; the\n\t// abort path clears the timer before rejecting with the verbatim `signal.reason`.\n\t#timer(ms: number, signal?: AbortSignal): Promise<void> {\n\t\tif (signal?.aborted === true) return Promise.reject(signal.reason)\n\t\treturn new Promise<void>((resolve, reject) => {\n\t\t\tconst onAbort = () => {\n\t\t\t\tclearTimeout(handle)\n\t\t\t\treject(signal?.reason)\n\t\t\t}\n\t\t\tconst handle = setTimeout(() => {\n\t\t\t\tsignal?.removeEventListener('abort', onAbort) // load-bearing: prevents a post-resolve reject\n\t\t\t\tresolve()\n\t\t\t}, ms)\n\t\t\tsignal?.addEventListener('abort', onAbort, { once: true })\n\t\t})\n\t}\n}\n","import type { SchedulerInterface, SchedulerOptions } from '@src/core'\n\n/**\n * The frame-aligned {@link SchedulerInterface} — a browser cooperative-yield backend\n * whose `yield` resumes just before the next paint via `requestAnimationFrame`.\n *\n * @remarks\n * - **`yield` resumes before the next paint.** `yield()` waits on `requestAnimationFrame`,\n *   so the resumption is aligned to the browser's render loop — ideal for work that\n *   should batch per frame (animation, incremental DOM updates) and pause while the tab\n *   is hidden (the host throttles rAF). `delay(ms)` is a real `setTimeout`, unaligned to\n *   frames. `options.priority` is accepted for contract compliance but a no-op — a frame\n *   callback has no priority dimension.\n * - **Abort fidelity is verbatim, with cleanup.** A pending `yield` / `delay` rejects with\n *   `signal.reason` exactly. The discipline mirrors the cross-environment default's\n *   `#sleep`: an already-aborted signal rejects immediately WITHOUT scheduling a frame;\n *   otherwise the frame is requested and a `{ once: true }` abort listener attached, and\n *   the two settle paths are mutually exclusive — the frame path removes the listener\n *   before resolving, and the abort path `cancelAnimationFrame`s the pending handle before\n *   rejecting. The promise settles exactly once, with no leaked frame request and no\n *   leaked listener.\n * - **Event-free.** A pure functional primitive — no Emitter, no events.\n *\n * @example\n * ```ts\n * import { createAbort } from '@src/core'\n * import { FrameScheduler } from '@src/browser'\n *\n * const abort = createAbort()\n * const scheduler = new FrameScheduler()\n * while (!abort.signal.aborted) {\n * \trenderOneFrameOfWork()\n * \tawait scheduler.yield({ signal: abort.signal }) // resume before the next paint\n * }\n * ```\n */\nexport class FrameScheduler implements SchedulerInterface {\n\t/**\n\t * Yield control to the host until just before the next paint via\n\t * `requestAnimationFrame`, then resume; abort rejects with `signal.reason`.\n\t */\n\tyield(options?: SchedulerOptions): Promise<void> {\n\t\treturn this.#frame(options?.signal)\n\t}\n\n\t/**\n\t * Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with\n\t * `signal.reason`.\n\t *\n\t * @remarks\n\t * `ms` should be a non-negative finite number. The primitive does no validation: it\n\t * passes `ms` straight to the host `setTimeout`, which clamps a negative value or\n\t * `NaN` to ~0 — so an out-of-domain `ms` resolves on the next host turn rather than\n\t * throwing.\n\t */\n\tdelay(ms: number, options?: SchedulerOptions): Promise<void> {\n\t\treturn this.#sleep(ms, options?.signal)\n\t}\n\n\t// === Private\n\n\t// The `requestAnimationFrame` host-turn for `yield`. Resolves in the next frame\n\t// callback (before paint); rejects with `signal.reason` if already aborted (no frame\n\t// requested) or aborted while pending. Settle-once, no leak: the frame path removes the\n\t// abort listener before resolving; the abort path cancels the frame before rejecting.\n\t#frame(signal?: AbortSignal): Promise<void> {\n\t\tif (signal?.aborted === true) return Promise.reject(signal.reason)\n\t\treturn new Promise<void>((resolve, reject) => {\n\t\t\tconst onAbort = () => {\n\t\t\t\tcancelAnimationFrame(handle)\n\t\t\t\treject(signal?.reason)\n\t\t\t}\n\t\t\tconst handle = requestAnimationFrame(() => {\n\t\t\t\tsignal?.removeEventListener('abort', onAbort) // load-bearing: prevents a post-resolve reject\n\t\t\t\tresolve()\n\t\t\t})\n\t\t\tsignal?.addEventListener('abort', onAbort, { once: true })\n\t\t})\n\t}\n\n\t// The abort-aware `setTimeout` sleep for `delay`. Same settle-once discipline as the\n\t// core `#sleep`: already-aborted → reject without arming; the timer path removes the\n\t// listener before resolving; the abort path clears the timer before rejecting with the\n\t// verbatim `signal.reason`.\n\t#sleep(ms: number, signal?: AbortSignal): Promise<void> {\n\t\tif (signal?.aborted === true) return Promise.reject(signal.reason)\n\t\treturn new Promise<void>((resolve, reject) => {\n\t\t\tconst onAbort = () => {\n\t\t\t\tclearTimeout(handle)\n\t\t\t\treject(signal?.reason)\n\t\t\t}\n\t\t\tconst handle = setTimeout(() => {\n\t\t\t\tsignal?.removeEventListener('abort', onAbort) // load-bearing: prevents a post-resolve reject\n\t\t\t\tresolve()\n\t\t\t}, ms)\n\t\t\tsignal?.addEventListener('abort', onAbort, { once: true })\n\t\t})\n\t}\n}\n","import type { SchedulerInterface, SchedulerOptions } from '@src/core'\nimport { isFunction } from '@orkestrel/contract'\nimport type { IdleAPI } from './types.js'\n\n/**\n * The idle-time {@link SchedulerInterface} — a browser cooperative-yield backend whose\n * `yield` resumes when the host is idle via `requestIdleCallback`, falling back to a\n * zero-delay macrotask where it is absent.\n *\n * @remarks\n * - **`yield` resumes during idle time.** When `globalThis` exposes `requestIdleCallback`,\n *   `yield()` waits on it, so the resumption happens when the browser has spare time after\n *   rendering and input — ideal for low-priority background work that must not contend with\n *   the user. The capability is feature-detected through a guard (`isFunction`), never an\n *   `as` (AGENTS §14). Where the API is absent (Safari today), it **falls back** to a\n *   `setTimeout(0)` macrotask — still a real host-turn, just not idle-gated. `delay(ms)` is\n *   always a real `setTimeout`. `options.priority` is accepted for contract compliance but a\n *   no-op — idle scheduling has no priority dimension.\n * - **Abort fidelity is verbatim, with cleanup.** A pending `yield` / `delay` rejects with\n *   `signal.reason` exactly. The discipline mirrors the cross-environment default's\n *   `#sleep`: an already-aborted signal rejects immediately WITHOUT scheduling; otherwise\n *   the idle callback (or fallback timer) is requested and a `{ once: true }` abort listener\n *   attached, and the two settle paths are mutually exclusive — the resume path removes the\n *   listener before resolving, and the abort path `cancelIdleCallback`s (or `clearTimeout`s)\n *   the pending handle before rejecting. The promise settles exactly once, with no leaked\n *   callback/timer and no leaked listener.\n * - **Event-free.** A pure functional primitive — no Emitter, no events.\n *\n * @example\n * ```ts\n * import { createAbort } from '@src/core'\n * import { IdleScheduler } from '@src/browser'\n *\n * const abort = createAbort()\n * const scheduler = new IdleScheduler()\n * while (!abort.signal.aborted) {\n * \tdoLowPriorityWork()\n * \tawait scheduler.yield({ signal: abort.signal }) // resume when the host is idle\n * }\n * ```\n */\nexport class IdleScheduler implements SchedulerInterface {\n\t/**\n\t * Yield control to the host until it is idle via `requestIdleCallback` (or a\n\t * `setTimeout(0)` macrotask where the API is absent), then resume; abort rejects with\n\t * `signal.reason`.\n\t */\n\tyield(options?: SchedulerOptions): Promise<void> {\n\t\tconst idle = this.#idleAPI()\n\t\tif (idle === undefined) return this.#sleep(0, options?.signal)\n\t\treturn this.#idle(idle, options?.signal)\n\t}\n\n\t/**\n\t * Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with\n\t * `signal.reason`.\n\t *\n\t * @remarks\n\t * `ms` should be a non-negative finite number. The primitive does no validation: it\n\t * passes `ms` straight to the host `setTimeout`, which clamps a negative value or\n\t * `NaN` to ~0 — so an out-of-domain `ms` resolves on the next host turn rather than\n\t * throwing.\n\t */\n\tdelay(ms: number, options?: SchedulerOptions): Promise<void> {\n\t\treturn this.#sleep(ms, options?.signal)\n\t}\n\n\t// === Private\n\n\t// Feature-detect `requestIdleCallback` / `cancelIdleCallback` off `globalThis` through\n\t// guards (no `as`): both must be callable. Returns the narrowed pair, or `undefined`\n\t// when the API is absent (the macrotask fallback).\n\t#idleAPI(): IdleAPI | undefined {\n\t\tconst request: unknown = Reflect.get(globalThis, 'requestIdleCallback')\n\t\tconst cancel: unknown = Reflect.get(globalThis, 'cancelIdleCallback')\n\t\tif (!isFunction(request) || !isFunction(cancel)) return undefined\n\t\treturn {\n\t\t\trequest: (callback) => Number(Reflect.apply(request, globalThis, [callback])),\n\t\t\tcancel: (handle) => {\n\t\t\t\tReflect.apply(cancel, globalThis, [handle])\n\t\t\t},\n\t\t}\n\t}\n\n\t// The `requestIdleCallback` host-turn for `yield`. Resolves in the idle callback;\n\t// rejects with `signal.reason` if already aborted (nothing scheduled) or aborted while\n\t// pending. Settle-once, no leak: the resume path removes the abort listener before\n\t// resolving; the abort path cancels the idle callback before rejecting.\n\t#idle(idle: IdleAPI, signal?: AbortSignal): Promise<void> {\n\t\tif (signal?.aborted === true) return Promise.reject(signal.reason)\n\t\treturn new Promise<void>((resolve, reject) => {\n\t\t\tconst onAbort = () => {\n\t\t\t\tidle.cancel(handle)\n\t\t\t\treject(signal?.reason)\n\t\t\t}\n\t\t\tconst handle = idle.request(() => {\n\t\t\t\tsignal?.removeEventListener('abort', onAbort) // load-bearing: prevents a post-resolve reject\n\t\t\t\tresolve()\n\t\t\t})\n\t\t\tsignal?.addEventListener('abort', onAbort, { once: true })\n\t\t})\n\t}\n\n\t// The abort-aware `setTimeout` sleep shared by `delay` and the `yield` macrotask\n\t// fallback. Same settle-once discipline as the core `#sleep`: already-aborted → reject\n\t// without arming; the timer path removes the listener before resolving; the abort path\n\t// clears the timer before rejecting with the verbatim `signal.reason`.\n\t#sleep(ms: number, signal?: AbortSignal): Promise<void> {\n\t\tif (signal?.aborted === true) return Promise.reject(signal.reason)\n\t\treturn new Promise<void>((resolve, reject) => {\n\t\t\tconst onAbort = () => {\n\t\t\t\tclearTimeout(handle)\n\t\t\t\treject(signal?.reason)\n\t\t\t}\n\t\t\tconst handle = setTimeout(() => {\n\t\t\t\tsignal?.removeEventListener('abort', onAbort) // load-bearing: prevents a post-resolve reject\n\t\t\t\tresolve()\n\t\t\t}, ms)\n\t\t\tsignal?.addEventListener('abort', onAbort, { once: true })\n\t\t})\n\t}\n}\n","import type { SchedulerInterface } from '@src/core'\nimport { BrowserScheduler } from './BrowserScheduler.js'\nimport { FrameScheduler } from './FrameScheduler.js'\nimport { IdleScheduler } from './IdleScheduler.js'\n\n/**\n * Create the browser-native cooperative-yield {@link SchedulerInterface} — `yield()` uses\n * the Prioritized Task Scheduling API (`scheduler.postTask`) at the requested priority\n * when present, falling back to a `setTimeout(0)` macrotask; `delay(ms)` is a real\n * `setTimeout`.\n *\n * @remarks\n * The default browser scheduler: it honours `options.priority` (`user` /\n * `normal` / `background`) when `scheduler.postTask` is available and degrades to a plain\n * macrotask elsewhere. Both methods are abort-aware: pass `options.signal` and a pending\n * yield/delay rejects with the signal's `reason` verbatim, with full task/timer/listener\n * cleanup. Prefer {@link createFrameScheduler} for paint-aligned work or\n * {@link createIdleScheduler} for idle-time background work.\n *\n * @returns A {@link SchedulerInterface} backed by `scheduler.postTask` (or a macrotask)\n *\n * @example\n * ```ts\n * import { createBrowserScheduler } from '@src/browser'\n *\n * const scheduler = createBrowserScheduler()\n * await scheduler.yield({ priority: 'background' })\n * ```\n */\nexport function createBrowserScheduler(): SchedulerInterface {\n\treturn new BrowserScheduler()\n}\n\n/**\n * Create the frame-aligned cooperative-yield {@link SchedulerInterface} — `yield()` resumes\n * just before the next paint via `requestAnimationFrame`; `delay(ms)` is a real\n * `setTimeout`.\n *\n * @remarks\n * Use it for work that should batch per render frame (animation, incremental DOM updates)\n * and naturally pause while the tab is hidden. `yield` is abort-aware: pass `options.signal`\n * and a pending yield rejects with the signal's `reason` verbatim, cancelling the pending\n * frame request. `options.priority` is accepted but a no-op — a frame callback has no\n * priority dimension.\n *\n * @returns A {@link SchedulerInterface} backed by `requestAnimationFrame`\n *\n * @example\n * ```ts\n * import { createFrameScheduler } from '@src/browser'\n *\n * const scheduler = createFrameScheduler()\n * await scheduler.yield() // resumes before the next paint\n * ```\n */\nexport function createFrameScheduler(): SchedulerInterface {\n\treturn new FrameScheduler()\n}\n\n/**\n * Create the idle-time cooperative-yield {@link SchedulerInterface} — `yield()` resumes when\n * the host is idle via `requestIdleCallback` when present, falling back to a `setTimeout(0)`\n * macrotask; `delay(ms)` is a real `setTimeout`.\n *\n * @remarks\n * Use it for low-priority background work that must not contend with rendering or input.\n * Where `requestIdleCallback` is absent (Safari today) it degrades to a plain macrotask.\n * `yield` is abort-aware: pass `options.signal` and a pending yield rejects with the\n * signal's `reason` verbatim, cancelling the pending idle callback. `options.priority` is\n * accepted but a no-op — idle scheduling has no priority dimension.\n *\n * @returns A {@link SchedulerInterface} backed by `requestIdleCallback` (or a macrotask)\n *\n * @example\n * ```ts\n * import { createIdleScheduler } from '@src/browser'\n *\n * const scheduler = createIdleScheduler()\n * await scheduler.yield() // resumes when the host is idle\n * ```\n */\nexport function createIdleScheduler(): SchedulerInterface {\n\treturn new IdleScheduler()\n}\n"],"mappings":"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"}