@orkestrel/workflow 0.0.16 → 0.0.18

package/README.md

@@ -1,8 +1,14 @@
 # @orkestrel/workflow
 
-A typed, host-independent workflow engine for the `@orkestrel` line. It keeps
-work as a serializable `Workflow → Phase → Task` tree and executes task behavior
-through a caller-supplied function registry on a cooperative scheduler.
+> Orchestration as data: a JSON-serializable `Workflow → Phase → Task` tree that a UI or an
+> LLM authors, a store persists, and a thin engine drives by composing the shipped execution
+> substrate.
+
+Author the definition as plain JSON, register the functions its tasks name, and
+hand both to the runner: it builds the live tree, runs each phase in turn with
+that phase's tasks concurrent, and resolves the settled result. Host-independent,
+with browser-native and Node-native scheduler backends beside the default. Part
+of the `@orkestrel` line.
 
 ## Install
 
@@ -33,13 +39,13 @@ attempt. Runtime pause gates are intentionally not persisted.
 
 Provider sessions, external processes, MCP projection, journals, leases, and
 distributed fencing remain integration concerns rather than core workflow
-behavior. See [guides/src/workflow.md](./guides/src/workflow.md) for the complete
-shipped contract. The proposed integration architecture now lives with the
+behavior. See [guides/workflow.md](./guides/workflow.md) for the complete
+shipped contract. The proposed integration architecture lives with the
 package that implements it, as `plan/PROPOSAL.md` in `@orkestrel/supervisor`.
 
 ## Package
 
-Published as three environment-scoped entry points: `.` provides the shared
+Published as environment-scoped entry points: `.` provides the shared
 environment-agnostic core and default scheduler, `./browser` adds browser-native
 schedulers, and `./server` adds the Node-native scheduler. Core ships dual
 ESM+CJS builds; `./browser` is ESM-only.

package/dist/src/browser/index.d.ts

@@ -1,11 +1,12 @@
-import { SchedulerInterface } from '@orkestrel/workflow';
-import { SchedulerOptions } from '@orkestrel/workflow';
-import { SchedulerPriority } from '@orkestrel/workflow';
+import type { SchedulerInterface } from '@orkestrel/workflow';
+import type { SchedulerOptions } from '@orkestrel/workflow';
+import type { SchedulerPriority } from '@orkestrel/workflow';
 
 /**
- * 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.
+ * Implements the browser {@link SchedulerInterface} — the browser-native cooperative-yield backend
+ * built on the Prioritized Task Scheduling API (`scheduler.postTask`) at the mapped priority,
+ * falling back to a zero-delay macrotask where it is absent, and rejecting an aborted wait
+ * with the caller's own reason.
  *
  * @remarks
  * - **`yield` prefers `scheduler.postTask`, honouring priority.** When `globalThis`
@@ -13,12 +14,12 @@ import { SchedulerPriority } from '@orkestrel/workflow';
  *   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`.
+ *   never an `as`. Where the API is absent (Firefox today, older engines),
+ *   it **falls back** to a `setTimeout(0)` macrotask — still a real host-turn, without
+ *   priority. `delay(ms)` is always a real `setTimeout`.
  * - **Abort fidelity is verbatim.** The shared `scheduleHost` lifecycle links an owned
  *   settlement composite before scheduling, preserving the exact caller reason without
- *   invoking caller-owned signal methods. The caller signal is NOT handed to `postTask`;
+ *   invoking caller-owned signal methods. The caller signal is not handed to `postTask`;
  *   an internal controller cancels that native task. An unexpected native promise rejection
  *   is routed back as the exact host failure instead of being discarded.
  * - **Event-free.** A pure functional primitive — no Emitter, no events.
@@ -39,26 +40,25 @@ import { SchedulerPriority } from '@orkestrel/workflow';
 export declare class BrowserScheduler implements SchedulerInterface {
     #private;
     /**
-     * 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
+     * Yields control to the host through `scheduler.postTask` at the given priority (or a
+     * `setTimeout(0)` macrotask where the API is absent), then resumes; abort rejects with
      * `signal.reason`.
      */
     yield(options?: SchedulerOptions): Promise<void>;
     /**
-     * Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with
+     * Resumes after at least `ms` milliseconds through `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.
+     * Pass a non-negative finite `ms`. 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: number, options?: SchedulerOptions): Promise<void>;
 }
 
 /**
- * Create the browser-native cooperative-yield {@link SchedulerInterface} — `yield()` uses
+ * Creates 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`.
@@ -85,13 +85,13 @@ export declare class BrowserScheduler implements SchedulerInterface {
 export declare function createBrowserScheduler(): SchedulerInterface;
 
 /**
- * Create the frame-aligned cooperative-yield {@link SchedulerInterface} — `yield()` resumes
- * just before the next paint via `requestAnimationFrame`; `delay(ms)` is a real
+ * Creates the frame-aligned cooperative-yield {@link SchedulerInterface} — `yield()` resumes
+ * before the next paint through `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`
+ * Use it for work that batches per render frame (animation, incremental DOM updates) and
+ * naturally pauses 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.
@@ -109,8 +109,8 @@ export declare function createBrowserScheduler(): SchedulerInterface;
 export declare function createFrameScheduler(): SchedulerInterface;
 
 /**
- * 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)`
+ * Creates the idle-time cooperative-yield {@link SchedulerInterface} — `yield()` resumes when
+ * the host is idle through `requestIdleCallback` when present, falling back to a `setTimeout(0)`
  * macrotask; `delay(ms)` is a real `setTimeout`.
  *
  * @remarks
@@ -133,14 +133,15 @@ export declare function createFrameScheduler(): SchedulerInterface;
 export declare function createIdleScheduler(): SchedulerInterface;
 
 /**
- * The frame-aligned {@link SchedulerInterface} — a browser cooperative-yield backend
- * whose `yield` resumes just before the next paint via `requestAnimationFrame`.
+ * Implements the frame-aligned {@link SchedulerInterface} — a browser cooperative-yield backend
+ * whose `yield` resumes before the next paint through `requestAnimationFrame`, rejecting an
+ * aborted wait with the caller's own reason. A `priority` hint is accepted and does nothing.
  *
  * @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
+ *   batches per frame (animation, incremental DOM updates) and pauses 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.** The shared `scheduleHost` lifecycle links
@@ -164,50 +165,50 @@ export declare function createIdleScheduler(): SchedulerInterface;
 export declare class FrameScheduler implements SchedulerInterface {
     #private;
     /**
-     * Yield control to the host until just before the next paint via
-     * `requestAnimationFrame`, then resume; abort rejects with `signal.reason`.
+     * Yields control to the host until the moment before the next paint through
+     * `requestAnimationFrame`, then resumes; abort rejects with `signal.reason`.
      */
     yield(options?: SchedulerOptions): Promise<void>;
     /**
-     * Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with
+     * Resumes after at least `ms` milliseconds through `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.
+     * Pass a non-negative finite `ms`. 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: number, options?: SchedulerOptions): Promise<void>;
 }
 
 /**
- * The narrowed `requestIdleCallback` / `cancelIdleCallback` pair feature-detected off
+ * Declares the narrowed `requestIdleCallback` / `cancelIdleCallback` pair feature-detected off
  * `globalThis`.
  *
  * @remarks
  * A `request` taking a callback and returning a numeric handle, and a `cancel` taking that
  * handle. {@link IdleScheduler} feature-detects the pair through a guard (`isFunction`,
- * never an `as` — AGENTS §14) and resolves to `undefined` when the API is absent (Safari
+ * never an `as`) and resolves to `undefined` when the API is absent (Safari
  * today), so `yield` falls back to a macrotask.
  */
-export declare interface IdleAPI {
+export declare interface IdleInterface {
     readonly request: (callback: () => void) => number;
     readonly cancel: (handle: number) => void;
 }
 
 /**
- * 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.
+ * Implements the idle-time {@link SchedulerInterface} — a browser cooperative-yield backend whose
+ * `yield` resumes when the host is idle through `requestIdleCallback`, falling back to a
+ * zero-delay macrotask where it is absent, and rejecting an aborted wait with the caller's own
+ * reason. A `priority` hint is accepted and does nothing.
  *
  * @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
+ *   `as`. Where the API is absent (Safari today), it **falls back** to a
+ *   `setTimeout(0)` macrotask — still a real host-turn, 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.** The shared `scheduleHost` lifecycle links
@@ -231,27 +232,27 @@ export declare interface IdleAPI {
 export declare class IdleScheduler implements SchedulerInterface {
     #private;
     /**
-     * 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
+     * Yields control to the host until it is idle through `requestIdleCallback` (or a
+     * `setTimeout(0)` macrotask where the API is absent), then resumes; abort rejects with
      * `signal.reason`.
      */
     yield(options?: SchedulerOptions): Promise<void>;
     /**
-     * Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with
+     * Resumes after at least `ms` milliseconds through `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.
+     * Pass a non-negative finite `ms`. 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: number, options?: SchedulerOptions): Promise<void>;
 }
 
 /**
- * The browser-native `postTask` priority for each portable {@link SchedulerPriority} — the
- * Prioritized Task Scheduling API's three levels.
+ * Maps each portable {@link SchedulerPriority} to the browser-native `postTask` priority —
+ * `user` to `'user-blocking'`, `normal` to `'user-visible'`, and `background` to
+ * `'background'`.
  *
  * @remarks
  * A `user` hint maps to the most urgent `'user-blocking'`, `normal` to the default

package/dist/src/browser/index.js

@@ -1,9 +1,10 @@
-import { scheduleHost } from "../core/index.js";
+import { delayHost, scheduleHost } from "../core/index.js";
 import { isFunction, isPromise, 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.
+* Maps each portable {@link SchedulerPriority} to the browser-native `postTask` priority —
+* `user` to `'user-blocking'`, `normal` to `'user-visible'`, and `background` to
+* `'background'`.
 *
 * @remarks
 * A `user` hint maps to the most urgent `'user-blocking'`, `normal` to the default
@@ -19,9 +20,10 @@ var POST_TASK_PRIORITY = Object.freeze({
 //#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.
+* Implements the browser {@link SchedulerInterface} — the browser-native cooperative-yield backend
+* built on the Prioritized Task Scheduling API (`scheduler.postTask`) at the mapped priority,
+* falling back to a zero-delay macrotask where it is absent, and rejecting an aborted wait
+* with the caller's own reason.
 *
 * @remarks
 * - **`yield` prefers `scheduler.postTask`, honouring priority.** When `globalThis`
@@ -29,12 +31,12 @@ var POST_TASK_PRIORITY = Object.freeze({
 *   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`.
+*   never an `as`. Where the API is absent (Firefox today, older engines),
+*   it **falls back** to a `setTimeout(0)` macrotask — still a real host-turn, without
+*   priority. `delay(ms)` is always a real `setTimeout`.
 * - **Abort fidelity is verbatim.** The shared `scheduleHost` lifecycle links an owned
 *   settlement composite before scheduling, preserving the exact caller reason without
-*   invoking caller-owned signal methods. The caller signal is NOT handed to `postTask`;
+*   invoking caller-owned signal methods. The caller signal is not handed to `postTask`;
 *   an internal controller cancels that native task. An unexpected native promise rejection
 *   is routed back as the exact host failure instead of being discarded.
 * - **Event-free.** A pure functional primitive — no Emitter, no events.
@@ -54,27 +56,26 @@ var POST_TASK_PRIORITY = Object.freeze({
 */
 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
+	* Yields control to the host through `scheduler.postTask` at the given priority (or a
+	* `setTimeout(0)` macrotask where the API is absent), then resumes; abort rejects with
 	* `signal.reason`.
 	*/
 	yield(options) {
 		const post = this.#postTask();
-		if (post === void 0) return this.#timer(0, options?.signal);
+		if (post === void 0) return delayHost(0, options?.signal);
 		return this.#yieldVia(post, options?.priority ?? "normal", options?.signal);
 	}
 	/**
-	* Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with
+	* Resumes after at least `ms` milliseconds through `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.
+	* Pass a non-negative finite `ms`. 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);
+		return delayHost(ms, options?.signal);
 	}
 	#postTask() {
 		const candidate = Reflect.get(globalThis, "scheduler");
@@ -94,24 +95,19 @@ var BrowserScheduler = class {
 			return () => internal.abort();
 		}, signal);
 	}
-	#timer(ms, signal) {
-		return scheduleHost((complete) => {
-			const handle = setTimeout(complete, ms);
-			return () => clearTimeout(handle);
-		}, signal);
-	}
 };
 //#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`.
+* Implements the frame-aligned {@link SchedulerInterface} — a browser cooperative-yield backend
+* whose `yield` resumes before the next paint through `requestAnimationFrame`, rejecting an
+* aborted wait with the caller's own reason. A `priority` hint is accepted and does nothing.
 *
 * @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
+*   batches per frame (animation, incremental DOM updates) and pauses 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.** The shared `scheduleHost` lifecycle links
@@ -134,24 +130,23 @@ var BrowserScheduler = class {
 */
 var FrameScheduler = class {
 	/**
-	* Yield control to the host until just before the next paint via
-	* `requestAnimationFrame`, then resume; abort rejects with `signal.reason`.
+	* Yields control to the host until the moment before the next paint through
+	* `requestAnimationFrame`, then resumes; abort rejects with `signal.reason`.
 	*/
 	yield(options) {
 		return this.#frame(options?.signal);
 	}
 	/**
-	* Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with
+	* Resumes after at least `ms` milliseconds through `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.
+	* Pass a non-negative finite `ms`. 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);
+		return delayHost(ms, options?.signal);
 	}
 	#frame(signal) {
 		return scheduleHost((complete) => {
@@ -159,27 +154,22 @@ var FrameScheduler = class {
 			return () => cancelAnimationFrame(handle);
 		}, signal);
 	}
-	#sleep(ms, signal) {
-		return scheduleHost((complete) => {
-			const handle = setTimeout(complete, ms);
-			return () => clearTimeout(handle);
-		}, signal);
-	}
 };
 //#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.
+* Implements the idle-time {@link SchedulerInterface} — a browser cooperative-yield backend whose
+* `yield` resumes when the host is idle through `requestIdleCallback`, falling back to a
+* zero-delay macrotask where it is absent, and rejecting an aborted wait with the caller's own
+* reason. A `priority` hint is accepted and does nothing.
 *
 * @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
+*   `as`. Where the API is absent (Safari today), it **falls back** to a
+*   `setTimeout(0)` macrotask — still a real host-turn, 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.** The shared `scheduleHost` lifecycle links
@@ -202,29 +192,28 @@ var FrameScheduler = class {
 */
 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
+	* Yields control to the host until it is idle through `requestIdleCallback` (or a
+	* `setTimeout(0)` macrotask where the API is absent), then resumes; abort rejects with
 	* `signal.reason`.
 	*/
 	yield(options) {
-		const idle = this.#idleAPI();
-		if (idle === void 0) return this.#sleep(0, options?.signal);
+		const idle = this.#idleCallback();
+		if (idle === void 0) return delayHost(0, options?.signal);
 		return this.#idle(idle, options?.signal);
 	}
 	/**
-	* Resume after at least `ms` milliseconds via `setTimeout`; abort rejects with
+	* Resumes after at least `ms` milliseconds through `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.
+	* Pass a non-negative finite `ms`. 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);
+		return delayHost(ms, options?.signal);
 	}
-	#idleAPI() {
+	#idleCallback() {
 		const request = Reflect.get(globalThis, "requestIdleCallback");
 		const cancel = Reflect.get(globalThis, "cancelIdleCallback");
 		if (!isFunction(request) || !isFunction(cancel)) return void 0;
@@ -239,12 +228,6 @@ var IdleScheduler = class {
 			return () => idle.cancel(handle);
 		}, signal);
 	}
-	#sleep(ms, signal) {
-		return scheduleHost((complete) => {
-			const handle = setTimeout(complete, ms);
-			return () => clearTimeout(handle);
-		}, signal);
-	}
 	#request(request, callback) {
 		return Number(Reflect.apply(request, globalThis, [callback]));
 	}
@@ -255,7 +238,7 @@ var IdleScheduler = class {
 //#endregion
 //#region src/browser/factories.ts
 /**
-* Create the browser-native cooperative-yield {@link SchedulerInterface} — `yield()` uses
+* Creates 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`.
@@ -283,13 +266,13 @@ 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
+* Creates the frame-aligned cooperative-yield {@link SchedulerInterface} — `yield()` resumes
+* before the next paint through `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`
+* Use it for work that batches per render frame (animation, incremental DOM updates) and
+* naturally pauses 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.
@@ -308,8 +291,8 @@ 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)`
+* Creates the idle-time cooperative-yield {@link SchedulerInterface} — `yield()` resumes when
+* the host is idle through `requestIdleCallback` when present, falling back to a `setTimeout(0)`
 * macrotask; `delay(ms)` is a real `setTimeout`.
 *
 * @remarks

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"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>> = Object.freeze({\n\tuser: 'user-blocking',\n\tnormal: 'user-visible',\n\tbackground: 'background',\n})\n","import type { SchedulerInterface, SchedulerOptions, SchedulerPriority } from '@src/core'\nimport { scheduleHost } from '@src/core'\nimport { isFunction, isPromise, 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.** The shared `scheduleHost` lifecycle links an owned\n *   settlement composite before scheduling, preserving the exact caller reason without\n *   invoking caller-owned signal methods. The caller signal is NOT handed to `postTask`;\n *   an internal controller cancels that native task. An unexpected native promise rejection\n *   is routed back as the exact host failure instead of being discarded.\n * - **Event-free.** A pure functional primitive — no Emitter, no events.\n *\n * @example\n * ```ts\n * import { createAbort } from '@orkestrel/abort'\n * import { BrowserScheduler } from '@orkestrel/workflow/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.#timer(0, 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` boundary with an internal cancellation controller; `scheduleHost`\n\t// owns caller linking and first-settlement arbitration, including native promise failure.\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\treturn scheduleHost((complete, failure) => {\n\t\t\tconst internal = new AbortController()\n\t\t\tconst task = post(complete, {\n\t\t\t\tpriority: POST_TASK_PRIORITY[priority],\n\t\t\t\tsignal: internal.signal,\n\t\t\t})\n\t\t\tif (isPromise(task)) void task.catch(failure)\n\t\t\treturn () => internal.abort()\n\t\t}, signal)\n\t}\n\n\t// The browser timer boundary shared by `delay` and fallback `yield`.\n\t#timer(ms: number, signal?: AbortSignal): Promise<void> {\n\t\treturn scheduleHost((complete) => {\n\t\t\tconst handle = setTimeout(complete, ms)\n\t\t\treturn () => clearTimeout(handle)\n\t\t}, signal)\n\t}\n}\n","import type { SchedulerInterface, SchedulerOptions } from '@src/core'\nimport { scheduleHost } 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.** The shared `scheduleHost` lifecycle links\n *   an owned settlement composite before requesting a frame, never invokes caller-owned\n *   signal methods, and cancels the native handle when abort wins.\n * - **Event-free.** A pure functional primitive — no Emitter, no events.\n *\n * @example\n * ```ts\n * import { createAbort } from '@orkestrel/abort'\n * import { FrameScheduler } from '@orkestrel/workflow/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 frame request boundary; `scheduleHost` owns cancellation lifecycle.\n\t#frame(signal?: AbortSignal): Promise<void> {\n\t\treturn scheduleHost((complete) => {\n\t\t\tconst handle = requestAnimationFrame(complete)\n\t\t\treturn () => cancelAnimationFrame(handle)\n\t\t}, signal)\n\t}\n\n\t// The browser timer boundary; `scheduleHost` owns cancellation lifecycle.\n\t#sleep(ms: number, signal?: AbortSignal): Promise<void> {\n\t\treturn scheduleHost((complete) => {\n\t\t\tconst handle = setTimeout(complete, ms)\n\t\t\treturn () => clearTimeout(handle)\n\t\t}, signal)\n\t}\n}\n","import type { SchedulerInterface, SchedulerOptions } from '@src/core'\nimport { scheduleHost } from '@src/core'\nimport type { AnyFunction } from '@orkestrel/contract'\nimport type { IdleAPI } from './types.js'\nimport { isFunction } from '@orkestrel/contract'\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.** The shared `scheduleHost` lifecycle links\n *   an owned settlement composite before scheduling, never invokes caller-owned signal\n *   methods, and cancels the idle callback or fallback timer when abort wins.\n * - **Event-free.** A pure functional primitive — no Emitter, no events.\n *\n * @example\n * ```ts\n * import { createAbort } from '@orkestrel/abort'\n * import { IdleScheduler } from '@orkestrel/workflow/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: this.#request.bind(this, request),\n\t\t\tcancel: this.#cancel.bind(this, cancel),\n\t\t}\n\t}\n\n\t// The idle callback boundary; `scheduleHost` owns cancellation lifecycle.\n\t#idle(idle: IdleAPI, signal?: AbortSignal): Promise<void> {\n\t\treturn scheduleHost((complete) => {\n\t\t\tconst handle = idle.request(complete)\n\t\t\treturn () => idle.cancel(handle)\n\t\t}, signal)\n\t}\n\n\t// The browser timer boundary shared by `delay` and fallback `yield`.\n\t#sleep(ms: number, signal?: AbortSignal): Promise<void> {\n\t\treturn scheduleHost((complete) => {\n\t\t\tconst handle = setTimeout(complete, ms)\n\t\t\treturn () => clearTimeout(handle)\n\t\t}, signal)\n\t}\n\n\t#request(request: AnyFunction, callback: () => void): number {\n\t\treturn Number(Reflect.apply(request, globalThis, [callback]))\n\t}\n\n\t#cancel(cancel: AnyFunction, handle: number): void {\n\t\tReflect.apply(cancel, globalThis, [handle])\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 exact `reason`; the shared owned-signal lifecycle\n * cancels the native handle without invoking caller listener methods. Prefer\n * {@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 '@orkestrel/workflow/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 '@orkestrel/workflow/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 '@orkestrel/workflow/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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"}
+{"version":3,"file":"index.js","names":[],"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 * Maps each portable {@link SchedulerPriority} to the browser-native `postTask` priority —\n * `user` to `'user-blocking'`, `normal` to `'user-visible'`, and `background` to\n * `'background'`.\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>> = Object.freeze({\n\tuser: 'user-blocking',\n\tnormal: 'user-visible',\n\tbackground: 'background',\n})\n","import type { SchedulerInterface, SchedulerOptions, SchedulerPriority } from '@src/core'\nimport { delayHost, scheduleHost } from '@src/core'\nimport { isFunction, isPromise, isRecord } from '@orkestrel/contract'\nimport { POST_TASK_PRIORITY } from './constants.js'\n\n/**\n * Implements the browser {@link SchedulerInterface} — the browser-native cooperative-yield backend\n * built on the Prioritized Task Scheduling API (`scheduler.postTask`) at the mapped priority,\n * falling back to a zero-delay macrotask where it is absent, and rejecting an aborted wait\n * with the caller's own reason.\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`. Where the API is absent (Firefox today, older engines),\n *   it **falls back** to a `setTimeout(0)` macrotask — still a real host-turn, without\n *   priority. `delay(ms)` is always a real `setTimeout`.\n * - **Abort fidelity is verbatim.** The shared `scheduleHost` lifecycle links an owned\n *   settlement composite before scheduling, preserving the exact caller reason without\n *   invoking caller-owned signal methods. The caller signal is not handed to `postTask`;\n *   an internal controller cancels that native task. An unexpected native promise rejection\n *   is routed back as the exact host failure instead of being discarded.\n * - **Event-free.** A pure functional primitive — no Emitter, no events.\n *\n * @example\n * ```ts\n * import { createAbort } from '@orkestrel/abort'\n * import { BrowserScheduler } from '@orkestrel/workflow/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 * Yields control to the host through `scheduler.postTask` at the given priority (or a\n\t * `setTimeout(0)` macrotask where the API is absent), then resumes; 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 delayHost(0, options?.signal)\n\t\treturn this.#yieldVia(post, options?.priority ?? 'normal', options?.signal)\n\t}\n\n\t/**\n\t * Resumes after at least `ms` milliseconds through `setTimeout`; abort rejects with\n\t * `signal.reason`.\n\t *\n\t * @remarks\n\t * Pass a non-negative finite `ms`. The primitive does no validation: it passes `ms`\n\t * straight to the host `setTimeout`, which clamps a negative value or `NaN` to ~0 — so an\n\t * out-of-domain `ms` resolves on the next host turn rather than throwing.\n\t */\n\tdelay(ms: number, options?: SchedulerOptions): Promise<void> {\n\t\treturn delayHost(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` boundary with an internal cancellation controller; `scheduleHost`\n\t// owns caller linking and first-settlement arbitration, including native promise failure.\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\treturn scheduleHost((complete, failure) => {\n\t\t\tconst internal = new AbortController()\n\t\t\tconst task = post(complete, {\n\t\t\t\tpriority: POST_TASK_PRIORITY[priority],\n\t\t\t\tsignal: internal.signal,\n\t\t\t})\n\t\t\tif (isPromise(task)) void task.catch(failure)\n\t\t\treturn () => internal.abort()\n\t\t}, signal)\n\t}\n}\n","import type { SchedulerInterface, SchedulerOptions } from '@src/core'\nimport { delayHost, scheduleHost } from '@src/core'\n\n/**\n * Implements the frame-aligned {@link SchedulerInterface} — a browser cooperative-yield backend\n * whose `yield` resumes before the next paint through `requestAnimationFrame`, rejecting an\n * aborted wait with the caller's own reason. A `priority` hint is accepted and does nothing.\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 *   batches per frame (animation, incremental DOM updates) and pauses while the tab is\n *   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.** The shared `scheduleHost` lifecycle links\n *   an owned settlement composite before requesting a frame, never invokes caller-owned\n *   signal methods, and cancels the native handle when abort wins.\n * - **Event-free.** A pure functional primitive — no Emitter, no events.\n *\n * @example\n * ```ts\n * import { createAbort } from '@orkestrel/abort'\n * import { FrameScheduler } from '@orkestrel/workflow/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 * Yields control to the host until the moment before the next paint through\n\t * `requestAnimationFrame`, then resumes; 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 * Resumes after at least `ms` milliseconds through `setTimeout`; abort rejects with\n\t * `signal.reason`.\n\t *\n\t * @remarks\n\t * Pass a non-negative finite `ms`. The primitive does no validation: it passes `ms`\n\t * straight to the host `setTimeout`, which clamps a negative value or `NaN` to ~0 — so an\n\t * out-of-domain `ms` resolves on the next host turn rather than throwing.\n\t */\n\tdelay(ms: number, options?: SchedulerOptions): Promise<void> {\n\t\treturn delayHost(ms, options?.signal)\n\t}\n\n\t// === Private\n\n\t// The frame request boundary; `scheduleHost` owns cancellation lifecycle.\n\t#frame(signal?: AbortSignal): Promise<void> {\n\t\treturn scheduleHost((complete) => {\n\t\t\tconst handle = requestAnimationFrame(complete)\n\t\t\treturn () => cancelAnimationFrame(handle)\n\t\t}, signal)\n\t}\n}\n","import type { SchedulerInterface, SchedulerOptions } from '@src/core'\nimport type { AnyFunction } from '@orkestrel/contract'\nimport type { IdleInterface } from './types.js'\nimport { delayHost, scheduleHost } from '@src/core'\nimport { isFunction } from '@orkestrel/contract'\n\n/**\n * Implements the idle-time {@link SchedulerInterface} — a browser cooperative-yield backend whose\n * `yield` resumes when the host is idle through `requestIdleCallback`, falling back to a\n * zero-delay macrotask where it is absent, and rejecting an aborted wait with the caller's own\n * reason. A `priority` hint is accepted and does nothing.\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`. Where the API is absent (Safari today), it **falls back** to a\n *   `setTimeout(0)` macrotask — still a real host-turn, 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.** The shared `scheduleHost` lifecycle links\n *   an owned settlement composite before scheduling, never invokes caller-owned signal\n *   methods, and cancels the idle callback or fallback timer when abort wins.\n * - **Event-free.** A pure functional primitive — no Emitter, no events.\n *\n * @example\n * ```ts\n * import { createAbort } from '@orkestrel/abort'\n * import { IdleScheduler } from '@orkestrel/workflow/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 * Yields control to the host until it is idle through `requestIdleCallback` (or a\n\t * `setTimeout(0)` macrotask where the API is absent), then resumes; abort rejects with\n\t * `signal.reason`.\n\t */\n\tyield(options?: SchedulerOptions): Promise<void> {\n\t\tconst idle = this.#idleCallback()\n\t\tif (idle === undefined) return delayHost(0, options?.signal)\n\t\treturn this.#idle(idle, options?.signal)\n\t}\n\n\t/**\n\t * Resumes after at least `ms` milliseconds through `setTimeout`; abort rejects with\n\t * `signal.reason`.\n\t *\n\t * @remarks\n\t * Pass a non-negative finite `ms`. The primitive does no validation: it passes `ms`\n\t * straight to the host `setTimeout`, which clamps a negative value or `NaN` to ~0 — so an\n\t * out-of-domain `ms` resolves on the next host turn rather than throwing.\n\t */\n\tdelay(ms: number, options?: SchedulerOptions): Promise<void> {\n\t\treturn delayHost(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#idleCallback(): IdleInterface | 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: this.#request.bind(this, request),\n\t\t\tcancel: this.#cancel.bind(this, cancel),\n\t\t}\n\t}\n\n\t// The idle yield boundary; `scheduleHost` owns cancellation lifecycle.\n\t#idle(idle: IdleInterface, signal?: AbortSignal): Promise<void> {\n\t\treturn scheduleHost((complete) => {\n\t\t\tconst handle = idle.request(complete)\n\t\t\treturn () => idle.cancel(handle)\n\t\t}, signal)\n\t}\n\n\t#request(request: AnyFunction, callback: () => void): number {\n\t\treturn Number(Reflect.apply(request, globalThis, [callback]))\n\t}\n\n\t#cancel(cancel: AnyFunction, handle: number): void {\n\t\tReflect.apply(cancel, globalThis, [handle])\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 * Creates 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 exact `reason`; the shared owned-signal lifecycle\n * cancels the native handle without invoking caller listener methods. Prefer\n * {@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 '@orkestrel/workflow/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 * Creates the frame-aligned cooperative-yield {@link SchedulerInterface} — `yield()` resumes\n * before the next paint through `requestAnimationFrame`; `delay(ms)` is a real\n * `setTimeout`.\n *\n * @remarks\n * Use it for work that batches per render frame (animation, incremental DOM updates) and\n * naturally pauses 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 '@orkestrel/workflow/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 * Creates the idle-time cooperative-yield {@link SchedulerInterface} — `yield()` resumes when\n * the host is idle through `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 '@orkestrel/workflow/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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"}