@askrjs/askr 0.0.28 → 0.0.29

package/dist/fx/fx.js

@@ -1 +1,212 @@
-import{globalScheduler as h}from"../runtime/scheduler.js";import{getCurrentComponentInstance as d}from"../runtime/component.js";import{logger as T}from"../dev/logger.js";import{noopEventListenerWithFlush as g,noopEventListener as F}from"./noop.js";function p(){if(d()!==null)throw new Error("[Askr] calling FX handler during render is not allowed. Move calls to event handlers or effects.")}function m(c){h.enqueue(()=>{try{c()}catch(u){T.error("[Askr] FX handler error:",u)}})}function A(c,u,e){const{leading:n=!1,trailing:o=!0}=e||{},r=d();if(r&&r.ssr)return g;let l=null,t=null,s=0;const i=function(f){p();const a=Date.now();t=f,l!==null&&(clearTimeout(l),l=null),n&&a-s>=c&&(m(()=>u.call(null,f)),s=a),o&&(l=setTimeout(()=>{t&&m(()=>u.call(null,t)),l=null,s=Date.now()},c))};return i.cancel=()=>{l!==null&&(clearTimeout(l),l=null),t=null},i.flush=()=>{if(l!==null){clearTimeout(l);const f=t;t=null,l=null,f&&m(()=>u.call(null,f))}},r&&r.cleanupFns.push(()=>{i.cancel()}),i}function C(c,u,e){const{leading:n=!0,trailing:o=!0}=e||{},r=d();if(r&&r.ssr)return F;let l=0,t=null,s=null;const i=function(f){p();const a=Date.now();if(s=f,n&&a-l>=c?(m(()=>u.call(null,f)),l=a,t!==null&&(clearTimeout(t),t=null)):!n&&l===0&&(l=a),o&&t===null){const w=c-(a-l);t=setTimeout(()=>{s&&m(()=>u.call(null,s)),l=Date.now(),t=null},Math.max(0,w))}};return i.cancel=()=>{t!==null&&(clearTimeout(t),t=null),s=null},r&&r.cleanupFns.push(()=>i.cancel()),i}function k(c){const u=d();if(u&&u.ssr)return F;let e=null,n=null;const o=()=>{e=(typeof requestAnimationFrame<"u"?requestAnimationFrame:t=>setTimeout(()=>t(Date.now()),16))(()=>{if(e=null,n){const t=n;n=null,m(()=>c.call(null,t))}})},r=function(l){p(),n=l,e===null&&o()};return r.cancel=()=>{e!==null&&(typeof cancelAnimationFrame<"u"&&typeof e=="number"?cancelAnimationFrame(e):clearTimeout(e),e=null),n=null},u&&u.cleanupFns.push(()=>r.cancel()),r}function E(c,u){p();const e=d();if(e&&e.ssr)return()=>{};let n=setTimeout(()=>{n=null,m(u)},c);const o=()=>{n!==null&&(clearTimeout(n),n=null)};return e&&e.cleanupFns.push(o),o}function q(c,u){p();const e=d();if(e&&e.ssr)return()=>{};let n=null,o=!1;typeof requestIdleCallback<"u"?(o=!0,n=requestIdleCallback(()=>{n=null,m(c)},u)):n=setTimeout(()=>{n=null,m(c)},0);const r=()=>{n!==null&&(o&&typeof cancelIdleCallback<"u"&&typeof n=="number"?cancelIdleCallback(n):clearTimeout(n),n=null)};return e&&e.cleanupFns.push(r),r}function D(c,u){p();const e=d();if(e&&e.ssr)return{cancel:()=>{}};const{maxAttempts:n=3,delayMs:o=100,backoff:r=i=>o*Math.pow(2,i)}=u||{};let l=!1;const t=i=>{l||h.enqueue(()=>{if(l)return;c().then(()=>{},()=>{if(!l&&i+1<n){const a=r(i);setTimeout(()=>{t(i+1)},a)}}).catch(a=>{T.error("[Askr] scheduleRetry error:",a)})})};t(0);const s=()=>{l=!0};return e&&e.cleanupFns.push(s),{cancel:s}}export{A as debounceEvent,k as rafEvent,q as scheduleIdle,D as scheduleRetry,E as scheduleTimeout,C as throttleEvent};
+import { logger } from "../dev/logger.js";
+import { globalScheduler } from "../runtime/scheduler.js";
+import { getCurrentComponentInstance } from "../runtime/component.js";
+import { noopEventListener, noopEventListenerWithFlush } from "./noop.js";
+//#region src/fx/fx.ts
+function throwIfDuringRender() {
+	if (getCurrentComponentInstance() !== null) throw new Error("[Askr] calling FX handler during render is not allowed. Move calls to event handlers or effects.");
+}
+/**
+* Helper: schedule a user callback through the global scheduler
+*/
+function enqueueUserCallback(fn) {
+	globalScheduler.enqueue(() => {
+		try {
+			fn();
+		} catch (err) {
+			logger.error("[Askr] FX handler error:", err);
+		}
+	});
+}
+function debounceEvent(ms, handler, options) {
+	const { leading = false, trailing = true } = options || {};
+	const inst = getCurrentComponentInstance();
+	if (inst && inst.ssr) return noopEventListenerWithFlush;
+	let timeoutId = null;
+	let lastEvent = null;
+	let lastCallTime = 0;
+	const debounced = function(ev) {
+		throwIfDuringRender();
+		const now = Date.now();
+		lastEvent = ev;
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+		if (leading && now - lastCallTime >= ms) {
+			enqueueUserCallback(() => handler.call(null, ev));
+			lastCallTime = now;
+		}
+		if (trailing) timeoutId = setTimeout(() => {
+			if (lastEvent) enqueueUserCallback(() => handler.call(null, lastEvent));
+			timeoutId = null;
+			lastCallTime = Date.now();
+		}, ms);
+	};
+	debounced.cancel = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+		lastEvent = null;
+	};
+	debounced.flush = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			const ev = lastEvent;
+			lastEvent = null;
+			timeoutId = null;
+			if (ev) enqueueUserCallback(() => handler.call(null, ev));
+		}
+	};
+	if (inst) (inst.cleanupFns ??= []).push(() => {
+		debounced.cancel();
+	});
+	return debounced;
+}
+function throttleEvent(ms, handler, options) {
+	const { leading = true, trailing = true } = options || {};
+	const inst = getCurrentComponentInstance();
+	if (inst && inst.ssr) return noopEventListener;
+	let lastCallTime = 0;
+	let timeoutId = null;
+	let lastEvent = null;
+	const throttled = function(ev) {
+		throwIfDuringRender();
+		const now = Date.now();
+		lastEvent = ev;
+		if (leading && now - lastCallTime >= ms) {
+			enqueueUserCallback(() => handler.call(null, ev));
+			lastCallTime = now;
+			if (timeoutId !== null) {
+				clearTimeout(timeoutId);
+				timeoutId = null;
+			}
+		} else if (!leading && lastCallTime === 0) lastCallTime = now;
+		if (trailing && timeoutId === null) {
+			const wait = ms - (now - lastCallTime);
+			timeoutId = setTimeout(() => {
+				if (lastEvent) enqueueUserCallback(() => handler.call(null, lastEvent));
+				lastCallTime = Date.now();
+				timeoutId = null;
+			}, Math.max(0, wait));
+		}
+	};
+	throttled.cancel = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+		lastEvent = null;
+	};
+	if (inst) (inst.cleanupFns ??= []).push(() => throttled.cancel());
+	return throttled;
+}
+function rafEvent(handler) {
+	const inst = getCurrentComponentInstance();
+	if (inst && inst.ssr) return noopEventListener;
+	let frameId = null;
+	let lastEvent = null;
+	const scheduleFrame = () => {
+		frameId = (typeof requestAnimationFrame !== "undefined" ? requestAnimationFrame : (cb) => setTimeout(() => cb(Date.now()), 16))(() => {
+			frameId = null;
+			if (lastEvent) {
+				const ev = lastEvent;
+				lastEvent = null;
+				enqueueUserCallback(() => handler.call(null, ev));
+			}
+		});
+	};
+	const fn = function(ev) {
+		throwIfDuringRender();
+		lastEvent = ev;
+		if (frameId === null) scheduleFrame();
+	};
+	fn.cancel = () => {
+		if (frameId !== null) {
+			if (typeof cancelAnimationFrame !== "undefined" && typeof frameId === "number") cancelAnimationFrame(frameId);
+			else clearTimeout(frameId);
+			frameId = null;
+		}
+		lastEvent = null;
+	};
+	if (inst) (inst.cleanupFns ??= []).push(() => fn.cancel());
+	return fn;
+}
+function scheduleTimeout(ms, fn) {
+	throwIfDuringRender();
+	const inst = getCurrentComponentInstance();
+	if (inst && inst.ssr) return () => {};
+	let id = setTimeout(() => {
+		id = null;
+		enqueueUserCallback(fn);
+	}, ms);
+	const cancel = () => {
+		if (id !== null) {
+			clearTimeout(id);
+			id = null;
+		}
+	};
+	if (inst) (inst.cleanupFns ??= []).push(cancel);
+	return cancel;
+}
+function scheduleIdle(fn, options) {
+	throwIfDuringRender();
+	const inst = getCurrentComponentInstance();
+	if (inst && inst.ssr) return () => {};
+	let id = null;
+	let usingRIC = false;
+	if (typeof requestIdleCallback !== "undefined") {
+		usingRIC = true;
+		id = requestIdleCallback(() => {
+			id = null;
+			enqueueUserCallback(fn);
+		}, options);
+	} else id = setTimeout(() => {
+		id = null;
+		enqueueUserCallback(fn);
+	}, 0);
+	const cancel = () => {
+		if (id !== null) {
+			if (usingRIC && typeof cancelIdleCallback !== "undefined" && typeof id === "number") cancelIdleCallback(id);
+			else clearTimeout(id);
+			id = null;
+		}
+	};
+	if (inst) (inst.cleanupFns ??= []).push(cancel);
+	return cancel;
+}
+function scheduleRetry(fn, options) {
+	throwIfDuringRender();
+	const inst = getCurrentComponentInstance();
+	if (inst && inst.ssr) return { cancel: () => {} };
+	const { maxAttempts = 3, delayMs = 100, backoff = (i) => delayMs * Math.pow(2, i) } = options || {};
+	let cancelled = false;
+	const attempt = (index) => {
+		if (cancelled) return;
+		globalScheduler.enqueue(() => {
+			if (cancelled) return;
+			fn().then(() => {}, () => {
+				if (cancelled) return;
+				if (index + 1 < maxAttempts) {
+					const delay = backoff(index);
+					setTimeout(() => {
+						attempt(index + 1);
+					}, delay);
+				}
+			}).catch((e) => {
+				logger.error("[Askr] scheduleRetry error:", e);
+			});
+		});
+	};
+	attempt(0);
+	const cancel = () => {
+		cancelled = true;
+	};
+	if (inst) (inst.cleanupFns ??= []).push(cancel);
+	return { cancel };
+}
+//#endregion
+export { debounceEvent, rafEvent, scheduleIdle, scheduleRetry, scheduleTimeout, throttleEvent };
+
+//# sourceMappingURL=fx.js.map

package/dist/fx/fx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx.js","names":[],"sources":["../../src/fx/fx.ts"],"sourcesContent":["import { globalScheduler } from '../runtime/scheduler';\nimport { getCurrentComponentInstance } from '../runtime/component';\nimport { logger } from '../dev/logger';\nimport { noopEventListener, noopEventListenerWithFlush } from './noop';\n\nexport type CancelFn = () => void;\n\n// Platform-specific timer handle types\ntype TimeoutHandle = ReturnType<typeof setTimeout> | null;\n// rAF may fall back to setTimeout in some environments/tests, include both\ntype RafHandle =\n  | ReturnType<typeof requestAnimationFrame>\n  | ReturnType<typeof setTimeout>\n  | null;\n// requestIdleCallback may be unavailable; allow setTimeout fallback handle\ntype IdleHandle =\n  | ReturnType<typeof requestIdleCallback>\n  | ReturnType<typeof setTimeout>\n  | null;\n\nfunction throwIfDuringRender(): void {\n  const inst = getCurrentComponentInstance();\n  if (inst !== null) {\n    throw new Error(\n      '[Askr] calling FX handler during render is not allowed. Move calls to event handlers or effects.'\n    );\n  }\n}\n\n/**\n * Helper: schedule a user callback through the global scheduler\n */\nfunction enqueueUserCallback(fn: () => void) {\n  globalScheduler.enqueue(() => {\n    try {\n      fn();\n    } catch (err) {\n      // Keep behavior consistent with other scheduler-queued work\n      logger.error('[Askr] FX handler error:', err);\n    }\n  });\n}\n\n// ---------- Event handlers ----------\n\nexport function debounceEvent(\n  ms: number,\n  handler: EventListener,\n  options?: { leading?: boolean; trailing?: boolean }\n): EventListener & { cancel(): void; flush(): void } {\n  const { leading = false, trailing = true } = options || {};\n\n  const inst = getCurrentComponentInstance();\n  // On SSR, event handlers are inert\n  if (inst && inst.ssr) {\n    return noopEventListenerWithFlush;\n  }\n\n  let timeoutId: TimeoutHandle = null;\n  let lastEvent: Event | null = null;\n  let lastCallTime = 0;\n\n  const debounced = function (this: unknown, ev: Event) {\n    // Disallow using returned handler during render\n    throwIfDuringRender();\n\n    const now = Date.now();\n    lastEvent = ev;\n\n    if (timeoutId !== null) {\n      clearTimeout(timeoutId);\n      timeoutId = null;\n    }\n\n    if (leading && now - lastCallTime >= ms) {\n      enqueueUserCallback(() => handler.call(null, ev));\n      lastCallTime = now;\n    }\n\n    if (trailing) {\n      timeoutId = setTimeout(() => {\n        // Schedule through scheduler\n        if (lastEvent) {\n          enqueueUserCallback(() => handler.call(null, lastEvent!));\n        }\n        timeoutId = null;\n        lastCallTime = Date.now();\n      }, ms);\n    }\n  } as EventListener & { cancel(): void; flush(): void };\n\n  debounced.cancel = () => {\n    if (timeoutId !== null) {\n      clearTimeout(timeoutId);\n      timeoutId = null;\n    }\n    lastEvent = null;\n  };\n\n  debounced.flush = () => {\n    if (timeoutId !== null) {\n      clearTimeout(timeoutId);\n      const ev = lastEvent;\n      lastEvent = null;\n      timeoutId = null;\n      if (ev) enqueueUserCallback(() => handler.call(null, ev));\n    }\n  };\n\n  // Auto-cleanup on component unmount\n  if (inst) {\n    (inst.cleanupFns ??= []).push(() => {\n      debounced.cancel();\n    });\n  }\n\n  return debounced;\n}\n\nexport function throttleEvent(\n  ms: number,\n  handler: EventListener,\n  options?: { leading?: boolean; trailing?: boolean }\n): EventListener & { cancel(): void } {\n  const { leading = true, trailing = true } = options || {};\n\n  const inst = getCurrentComponentInstance();\n  if (inst && inst.ssr) {\n    return noopEventListener;\n  }\n\n  let lastCallTime = 0;\n  let timeoutId: TimeoutHandle = null;\n  let lastEvent: Event | null = null;\n\n  const throttled = function (this: unknown, ev: Event) {\n    throwIfDuringRender();\n\n    const now = Date.now();\n    lastEvent = ev;\n\n    if (leading && now - lastCallTime >= ms) {\n      enqueueUserCallback(() => handler.call(null, ev));\n      lastCallTime = now;\n      if (timeoutId !== null) {\n        clearTimeout(timeoutId);\n        timeoutId = null;\n      }\n    } else if (!leading && lastCallTime === 0) {\n      lastCallTime = now;\n    }\n\n    if (trailing && timeoutId === null) {\n      const wait = ms - (now - lastCallTime);\n      timeoutId = setTimeout(\n        () => {\n          if (lastEvent)\n            enqueueUserCallback(() => handler.call(null, lastEvent!));\n          lastCallTime = Date.now();\n          timeoutId = null;\n        },\n        Math.max(0, wait)\n      );\n    }\n  } as EventListener & { cancel(): void };\n\n  throttled.cancel = () => {\n    if (timeoutId !== null) {\n      clearTimeout(timeoutId);\n      timeoutId = null;\n    }\n    lastEvent = null;\n  };\n\n  if (inst) {\n    (inst.cleanupFns ??= []).push(() => throttled.cancel());\n  }\n\n  return throttled;\n}\n\nexport function rafEvent(\n  handler: EventListener\n): EventListener & { cancel(): void } {\n  const inst = getCurrentComponentInstance();\n  if (inst && inst.ssr) {\n    return noopEventListener;\n  }\n\n  let frameId: RafHandle = null;\n  let lastEvent: Event | null = null;\n\n  const scheduleFrame = () => {\n    const rAF =\n      typeof requestAnimationFrame !== 'undefined'\n        ? requestAnimationFrame\n        : (cb: FrameRequestCallback) => setTimeout(() => cb(Date.now()), 16);\n\n    frameId = rAF(() => {\n      frameId = null;\n      if (lastEvent) {\n        const ev = lastEvent;\n        lastEvent = null;\n        enqueueUserCallback(() => handler.call(null, ev));\n      }\n    });\n  };\n\n  const fn = function (this: unknown, ev: Event) {\n    throwIfDuringRender();\n    lastEvent = ev;\n    if (frameId === null) scheduleFrame();\n  } as EventListener & { cancel(): void };\n\n  fn.cancel = () => {\n    if (frameId !== null) {\n      // If frameId is numeric and cancelAnimationFrame is available, use it;\n      // otherwise fall back to clearTimeout for the setTimeout fallback.\n      if (\n        typeof cancelAnimationFrame !== 'undefined' &&\n        typeof frameId === 'number'\n      ) {\n        cancelAnimationFrame(frameId);\n      } else {\n        clearTimeout(frameId as ReturnType<typeof setTimeout>);\n      }\n      frameId = null;\n    }\n    lastEvent = null;\n  };\n\n  if (inst) (inst.cleanupFns ??= []).push(() => fn.cancel());\n\n  return fn;\n}\n\n// ---------- Scheduled work ----------\n\nexport function scheduleTimeout(ms: number, fn: () => void): CancelFn {\n  throwIfDuringRender();\n  const inst = getCurrentComponentInstance();\n  if (inst && inst.ssr) {\n    return () => {};\n  }\n\n  let id: TimeoutHandle = setTimeout(() => {\n    id = null;\n    enqueueUserCallback(fn);\n  }, ms);\n\n  const cancel = () => {\n    if (id !== null) {\n      clearTimeout(id);\n      id = null;\n    }\n  };\n\n  if (inst) (inst.cleanupFns ??= []).push(cancel);\n  return cancel;\n}\n\nexport function scheduleIdle(\n  fn: () => void,\n  options?: { timeout?: number }\n): CancelFn {\n  throwIfDuringRender();\n  const inst = getCurrentComponentInstance();\n  if (inst && inst.ssr) return () => {};\n\n  let id: IdleHandle = null;\n  let usingRIC = false;\n\n  if (typeof requestIdleCallback !== 'undefined') {\n    usingRIC = true;\n    id = requestIdleCallback(() => {\n      id = null;\n      enqueueUserCallback(fn);\n    }, options);\n  } else {\n    // Fallback: schedule on next macrotask\n    id = setTimeout(() => {\n      id = null;\n      enqueueUserCallback(fn);\n    }, 0);\n  }\n\n  const cancel = () => {\n    if (id !== null) {\n      // If using requestIdleCallback and available, call cancelIdleCallback for numeric ids.\n      if (\n        usingRIC &&\n        typeof cancelIdleCallback !== 'undefined' &&\n        typeof id === 'number'\n      ) {\n        cancelIdleCallback(id);\n      } else {\n        clearTimeout(id as ReturnType<typeof setTimeout>);\n      }\n      id = null;\n    }\n  };\n\n  if (inst) (inst.cleanupFns ??= []).push(cancel);\n  return cancel;\n}\n\nexport interface RetryOptions {\n  maxAttempts?: number;\n  delayMs?: number;\n  backoff?: (attemptIndex: number) => number;\n}\n\nexport function scheduleRetry<T>(\n  fn: () => Promise<T>,\n  options?: RetryOptions\n): { cancel(): void } {\n  throwIfDuringRender();\n  const inst = getCurrentComponentInstance();\n  if (inst && inst.ssr) return { cancel: () => {} };\n\n  const {\n    maxAttempts = 3,\n    delayMs = 100,\n    backoff = (i: number) => delayMs * Math.pow(2, i),\n  } = options || {};\n\n  let cancelled = false;\n\n  const attempt = (index: number) => {\n    if (cancelled) return;\n    // Run user fn inside scheduler\n    globalScheduler.enqueue(() => {\n      if (cancelled) return;\n      // Call fn (it may be async)\n      const p = fn();\n      p.then(\n        () => {\n          // Completed successfully\n        },\n        () => {\n          if (cancelled) return;\n          if (index + 1 < maxAttempts) {\n            const delay = backoff(index);\n            // Schedule next attempt via setTimeout so it gets enqueued through scheduleTimeout\n            setTimeout(() => {\n              attempt(index + 1);\n            }, delay);\n          }\n        }\n      ).catch((e) => {\n        logger.error('[Askr] scheduleRetry error:', e);\n      });\n    });\n  };\n\n  // Start first attempt\n  attempt(0);\n\n  const cancel = () => {\n    cancelled = true;\n  };\n\n  if (inst) (inst.cleanupFns ??= []).push(cancel);\n  return { cancel };\n}\n"],"mappings":"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"}

package/dist/fx/index.d.ts

@@ -1,7 +1,4 @@
-/**
- * Standard library — pure helpers for common patterns
- * Zero framework coupling
- */
-export { debounce, throttle, once, defer, raf, idle, timeout, retry, type DebounceOptions, type ThrottleOptions, type RetryOptions, } from './timing';
-export { debounceEvent, throttleEvent, rafEvent, scheduleTimeout, scheduleIdle, scheduleRetry, } from './fx';
-//# sourceMappingURL=index.d.ts.map
+import { scheduleEventHandler } from "../runtime/scheduler.js";
+import { DebounceOptions, RetryOptions, ThrottleOptions, debounce, defer, idle, once, raf, retry, throttle, timeout } from "./timing.js";
+import { debounceEvent, rafEvent, scheduleIdle, scheduleRetry, scheduleTimeout, throttleEvent } from "./fx.js";
+export { type DebounceOptions, type RetryOptions, type ThrottleOptions, debounce, debounceEvent, defer, idle, once, raf, rafEvent, retry, scheduleEventHandler, scheduleIdle, scheduleRetry, scheduleTimeout, throttle, throttleEvent, timeout };

package/dist/fx/index.js

@@ -1 +1,4 @@
-import{debounce as r,defer as o,idle as d,once as l,raf as u,retry as c,throttle as n,timeout as f}from"./timing.js";import{debounceEvent as m,rafEvent as i,scheduleIdle as s,scheduleRetry as v,scheduleTimeout as E,throttleEvent as a}from"./fx.js";export{r as debounce,m as debounceEvent,o as defer,d as idle,l as once,u as raf,i as rafEvent,c as retry,s as scheduleIdle,v as scheduleRetry,E as scheduleTimeout,n as throttle,a as throttleEvent,f as timeout};
+import { scheduleEventHandler } from "../runtime/scheduler.js";
+import { debounce, defer, idle, once, raf, retry, throttle, timeout } from "./timing.js";
+import { debounceEvent, rafEvent, scheduleIdle, scheduleRetry, scheduleTimeout, throttleEvent } from "./fx.js";
+export { debounce, debounceEvent, defer, idle, once, raf, rafEvent, retry, scheduleEventHandler, scheduleIdle, scheduleRetry, scheduleTimeout, throttle, throttleEvent, timeout };

package/dist/fx/noop.js

@@ -1 +1,9 @@
-const e=()=>{},c=Object.assign(n=>{},{cancel(){}}),o=Object.assign(n=>{},{cancel(){},flush(){}}),s={cancel(){}};export{e as noop,s as noopCancel,c as noopEventListener,o as noopEventListenerWithFlush};
+const noopEventListener = Object.assign((_ev) => {}, { cancel() {} });
+const noopEventListenerWithFlush = Object.assign((_ev) => {}, {
+	cancel() {},
+	flush() {}
+});
+//#endregion
+export { noopEventListener, noopEventListenerWithFlush };
+
+//# sourceMappingURL=noop.js.map

package/dist/fx/noop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.js","names":[],"sources":["../../src/fx/noop.ts"],"sourcesContent":["// Lightweight shared no-op helpers to avoid double-casts and duplicated definitions\n\nexport const noop: () => void = () => {};\n\nexport const noopEventListener: EventListener & { cancel(): void } =\n  Object.assign((_ev?: Event) => {}, { cancel() {} });\n\nexport const noopEventListenerWithFlush: EventListener & {\n  cancel(): void;\n  flush(): void;\n} = Object.assign((_ev?: Event) => {}, { cancel() {}, flush() {} });\n\nexport const noopCancel: { cancel(): void } = { cancel() {} };\n"],"mappings":"AAIA,MAAa,oBACX,OAAO,QAAQ,QAAgB,IAAI,EAAE,SAAS,IAAI,CAAC;AAErD,MAAa,6BAGT,OAAO,QAAQ,QAAgB,IAAI;CAAE,SAAS;CAAI,QAAQ;CAAI,CAAC"}

package/dist/fx/timing.d.ts

@@ -1,19 +1,20 @@
+//#region src/fx/timing.d.ts
 /**
  * Timing utilities — pure helpers for common async patterns
  * No framework coupling. No lifecycle awareness.
  */
-export interface DebounceOptions {
-    leading?: boolean;
-    trailing?: boolean;
+interface DebounceOptions {
+  leading?: boolean;
+  trailing?: boolean;
 }
-export interface ThrottleOptions {
-    leading?: boolean;
-    trailing?: boolean;
+interface ThrottleOptions {
+  leading?: boolean;
+  trailing?: boolean;
 }
-export interface RetryOptions {
-    maxAttempts?: number;
-    delayMs?: number;
-    backoff?: (attemptIndex: number) => number;
+interface RetryOptions {
+  maxAttempts?: number;
+  delayMs?: number;
+  backoff?: (attemptIndex: number) => number;
 }
 /**
  * Debounce — delay execution, coalesce rapid calls
@@ -32,8 +33,8 @@ export interface RetryOptions {
  * save.cancel(); // stop any pending execution
  * ```
  */
-export declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, ms: number, options?: DebounceOptions): T & {
-    cancel(): void;
+declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, ms: number, options?: DebounceOptions): T & {
+  cancel(): void;
 };
 /**
  * Throttle — rate-limit execution, keep first/last
@@ -52,8 +53,8 @@ export declare function debounce<T extends (...args: unknown[]) => unknown>(fn:
  * handleScroll.cancel();
  * ```
  */
-export declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, ms: number, options?: ThrottleOptions): T & {
-    cancel(): void;
+declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, ms: number, options?: ThrottleOptions): T & {
+  cancel(): void;
 };
 /**
  * Once — guard against double execution
@@ -71,7 +72,7 @@ export declare function throttle<T extends (...args: unknown[]) => unknown>(fn:
  * init(); // does nothing
  * ```
  */
-export declare function once<T extends (...args: unknown[]) => unknown>(fn: T): T;
+declare function once<T extends (...args: unknown[]) => unknown>(fn: T): T;
 /**
  * Defer — schedule on microtask queue
  *
@@ -85,7 +86,7 @@ export declare function once<T extends (...args: unknown[]) => unknown>(fn: T):
  * defer(() => update()); // runs after current stack, before next macrotask
  * ```
  */
-export declare function defer(fn: () => void): void;
+declare function defer(fn: () => void): void;
 /**
  * RAF — coalesce multiple updates into single frame
  *
@@ -101,7 +102,7 @@ export declare function defer(fn: () => void): void;
  * update(); // same frame, no duplicate
  * ```
  */
-export declare function raf<T extends (...args: unknown[]) => unknown>(fn: T): T;
+declare function raf<T extends (...args: unknown[]) => unknown>(fn: T): T;
 /**
  * Idle — schedule low-priority work
  *
@@ -116,8 +117,8 @@ export declare function raf<T extends (...args: unknown[]) => unknown>(fn: T): T
  * idle(() => prefetchData());
  * ```
  */
-export declare function idle(fn: () => void, options?: {
-    timeout?: number;
+declare function idle(fn: () => void, options?: {
+  timeout?: number;
 }): void;
 /**
  * Timeout — Promise-based delay
@@ -133,7 +134,7 @@ export declare function idle(fn: () => void, options?: {
  * console.log('300ms later');
  * ```
  */
-export declare function timeout(ms: number): Promise<void>;
+declare function timeout(ms: number): Promise<void>;
 /**
  * Retry — attempt function with backoff
  *
@@ -151,5 +152,7 @@ export declare function timeout(ms: number): Promise<void>;
  * });
  * ```
  */
-export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+//#endregion
+export { DebounceOptions, RetryOptions, ThrottleOptions, debounce, defer, idle, once, raf, retry, throttle, timeout };
 //# sourceMappingURL=timing.d.ts.map

package/dist/fx/timing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../../src/fx/timing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAChE,EAAE,EAAE,CAAC,EACL,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,eAAe,GACxB,CAAC,GAAG;IAAE,MAAM,IAAI,IAAI,CAAA;CAAE,CAuCxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAChE,EAAE,EAAE,CAAC,EACL,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,eAAe,GACxB,CAAC,GAAG;IAAE,MAAM,IAAI,IAAI,CAAA;CAAE,CA4CxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAWxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAE1C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAiBvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASzE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,CAAC,CAAC,CAsBZ"}
+{"version":3,"file":"timing.d.ts","names":[],"sources":["../../src/fx/timing.ts"],"mappings":";;AAKA;;;UAAiB,eAAA;EACf,OAAA;EACA,QAAA;AAAA;AAAA,UAGe,eAAA;EACf,OAAA;EACA,QAAA;AAAA;AAAA,UAGe,YAAA;EACf,WAAA;EACA,OAAA;EACA,OAAA,IAAW,YAAA;AAAA;;;;;AAoBb;;;;;;;;;;;;;iBAAgB,QAAA,eAAuB,IAAA,wBAAA,CACrC,EAAA,EAAI,CAAA,EACJ,EAAA,UACA,OAAA,GAAU,eAAA,GACT,CAAA;EAAM,MAAA;AAAA;;;;AA0DT;;;;;;;;;;;;;;iBAAgB,QAAA,eAAuB,IAAA,wBAAA,CACrC,EAAA,EAAI,CAAA,EACJ,EAAA,UACA,OAAA,GAAU,eAAA,GACT,CAAA;EAAM,MAAA;AAAA;;;AA8DT;;;;;;;;;;;AA0BA;;;iBA1BgB,IAAA,eAAmB,IAAA,wBAAA,CAA6B,EAAA,EAAI,CAAA,GAAI,CAAA;;AA6CxE;;;;;;;;;;;AAiCA;iBApDgB,KAAA,CAAM,EAAA;;;;;;;;AA6EtB;;;;;AAqBA;;;iBA/EgB,GAAA,eAAkB,IAAA,wBAAA,CAA6B,EAAA,EAAI,CAAA,GAAI,CAAA;;;;;;;;;;;;;;;iBAiCvD,IAAA,CAAK,EAAA,cAAgB,OAAA;EAAY,OAAA;AAAA;;;;;;;;;;;;;;;iBAyBjC,OAAA,CAAQ,EAAA,WAAa,OAAA;;;;;;;;;;;;;;;;;;iBAqBf,KAAA,GAAA,CACpB,EAAA,QAAU,OAAA,CAAQ,CAAA,GAClB,OAAA,GAAU,YAAA,GACT,OAAA,CAAQ,CAAA"}

package/dist/fx/timing.js

@@ -1 +1,236 @@
-function d(e,l,i){let t=null;const{leading:n=!1,trailing:o=!0}=i||{};let u=null,a=null,r=0;const c=function(...f){const s=Date.now();u=f,a=this,t!==null&&clearTimeout(t),n&&s-r>=l&&(e.apply(this,f),r=s),o&&(t=setTimeout(()=>{e.apply(a,u),t=null,r=Date.now()},l))};return c.cancel=()=>{t!==null&&(clearTimeout(t),t=null)},c}function h(e,l,i){let t=0,n=null;const{leading:o=!0,trailing:u=!0}=i||{};let a=null,r=null;const c=function(...f){const s=Date.now();a=f,r=this,o&&s-t>=l?(e.apply(this,f),t=s,n!==null&&(clearTimeout(n),n=null)):!o&&t===0&&(t=s),u&&n===null&&(n=setTimeout(()=>{e.apply(r,a),t=Date.now(),n=null},l-(s-t)))};return c.cancel=()=>{n!==null&&(clearTimeout(n),n=null)},c}function T(e){let l=!1,i;return((...t)=>(l||(l=!0,i=e(...t)),i))}function p(e){Promise.resolve().then(e)}function y(e){let l=null,i=null,t=null;return function(...n){i=n,t=this,l===null&&(l=requestAnimationFrame(()=>{e.apply(t,i),l=null}))}}function w(e,l){typeof requestIdleCallback<"u"?requestIdleCallback(e,l?{timeout:l.timeout}:void 0):Promise.resolve().then(()=>{setTimeout(e,0)})}function m(e){return new Promise(l=>setTimeout(l,e))}async function b(e,l){const{maxAttempts:i=3,delayMs:t=100,backoff:n=u=>t*Math.pow(2,u)}=l||{};let o=null;for(let u=0;u<i;u++)try{return await e()}catch(a){if(o=a,u<i-1){const r=n(u);await m(r)}}throw o||new Error("Retry failed")}export{d as debounce,p as defer,w as idle,T as once,y as raf,b as retry,h as throttle,m as timeout};
+//#region src/fx/timing.ts
+/**
+* Debounce — delay execution, coalesce rapid calls
+*
+* Useful for: text input, resize, autosave
+*
+* @param fn Function to debounce
+* @param ms Delay in milliseconds
+* @param options trailing (default true), leading
+* @returns Debounced function with cancel() method
+*
+* @example
+* ```ts
+* const save = debounce((text) => api.save(text), 500);
+* input.addEventListener('input', (e) => save(e.target.value));
+* save.cancel(); // stop any pending execution
+* ```
+*/
+function debounce(fn, ms, options) {
+	let timeoutId = null;
+	const { leading = false, trailing = true } = options || {};
+	let lastArgs = null;
+	let lastThis = null;
+	let lastCallTime = 0;
+	const debounced = function(...args) {
+		const callTime = Date.now();
+		lastArgs = args;
+		lastThis = this;
+		if (timeoutId !== null) clearTimeout(timeoutId);
+		if (leading && callTime - lastCallTime >= ms) {
+			fn.apply(this, args);
+			lastCallTime = callTime;
+		}
+		if (trailing) timeoutId = setTimeout(() => {
+			fn.apply(lastThis, lastArgs);
+			timeoutId = null;
+			lastCallTime = Date.now();
+		}, ms);
+	};
+	debounced.cancel = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+	};
+	return debounced;
+}
+/**
+* Throttle — rate-limit execution, keep first/last
+*
+* Useful for: scroll, mouse move, high-frequency events
+*
+* @param fn Function to throttle
+* @param ms Minimum interval between calls in milliseconds
+* @param options leading (default true), trailing (default true)
+* @returns Throttled function with cancel() method
+*
+* @example
+* ```ts
+* const handleScroll = throttle(updateUI, 100);
+* window.addEventListener('scroll', handleScroll);
+* handleScroll.cancel();
+* ```
+*/
+function throttle(fn, ms, options) {
+	let lastCallTime = 0;
+	let timeoutId = null;
+	const { leading = true, trailing = true } = options || {};
+	let lastArgs = null;
+	let lastThis = null;
+	const throttled = function(...args) {
+		const callTime = Date.now();
+		lastArgs = args;
+		lastThis = this;
+		if (leading && callTime - lastCallTime >= ms) {
+			fn.apply(this, args);
+			lastCallTime = callTime;
+			if (timeoutId !== null) {
+				clearTimeout(timeoutId);
+				timeoutId = null;
+			}
+		} else if (!leading && lastCallTime === 0) lastCallTime = callTime;
+		if (trailing && timeoutId === null) timeoutId = setTimeout(() => {
+			fn.apply(lastThis, lastArgs);
+			lastCallTime = Date.now();
+			timeoutId = null;
+		}, ms - (callTime - lastCallTime));
+	};
+	throttled.cancel = () => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+	};
+	return throttled;
+}
+/**
+* Once — guard against double execution
+*
+* Useful for: init logic, event safety
+*
+* @param fn Function to call at most once
+* @returns Function that executes fn only on first call
+*
+* @example
+* ```ts
+* const init = once(setup);
+* init(); // runs
+* init(); // does nothing
+* init(); // does nothing
+* ```
+*/
+function once(fn) {
+	let called = false;
+	let result;
+	return ((...args) => {
+		if (!called) {
+			called = true;
+			result = fn(...args);
+		}
+		return result;
+	});
+}
+/**
+* Defer — schedule on microtask queue
+*
+* Useful for: run-after-current-stack logic
+* More reliable than setTimeout(..., 0)
+*
+* @param fn Function to defer
+*
+* @example
+* ```ts
+* defer(() => update()); // runs after current stack, before next macrotask
+* ```
+*/
+function defer(fn) {
+	Promise.resolve().then(fn);
+}
+/**
+* RAF — coalesce multiple updates into single frame
+*
+* Useful for: animation, layout work, render updates
+*
+* @param fn Function to schedule on next animation frame
+* @returns Function that schedules fn on requestAnimationFrame
+*
+* @example
+* ```ts
+* const update = raf(render);
+* update(); // schedules on next frame
+* update(); // same frame, no duplicate
+* ```
+*/
+function raf(fn) {
+	let frameId = null;
+	let lastArgs = null;
+	let lastThis = null;
+	return function(...args) {
+		lastArgs = args;
+		lastThis = this;
+		if (frameId === null) frameId = requestAnimationFrame(() => {
+			fn.apply(lastThis, lastArgs);
+			frameId = null;
+		});
+	};
+}
+/**
+* Idle — schedule low-priority work
+*
+* Useful for: background prep, non-urgent updates
+* Falls back to setTimeout if requestIdleCallback unavailable
+*
+* @param fn Function to call when idle
+* @param options timeout for fallback
+*
+* @example
+* ```ts
+* idle(() => prefetchData());
+* ```
+*/
+function idle(fn, options) {
+	if (typeof requestIdleCallback !== "undefined") requestIdleCallback(fn, options ? { timeout: options.timeout } : void 0);
+	else Promise.resolve().then(() => {
+		setTimeout(fn, 0);
+	});
+}
+/**
+* Timeout — Promise-based delay
+*
+* Useful for: readable async code, waiting between retries
+*
+* @param ms Milliseconds to wait
+* @returns Promise that resolves after delay
+*
+* @example
+* ```ts
+* await timeout(300);
+* console.log('300ms later');
+* ```
+*/
+function timeout(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Retry — attempt function with backoff
+*
+* Useful for: network calls, transient failures
+*
+* @param fn Async function to retry
+* @param options maxAttempts, delayMs, backoff function
+* @returns Promise with final result or error
+*
+* @example
+* ```ts
+* const data = await retry(() => fetch(url), {
+*   maxAttempts: 3,
+*   delayMs: 100,
+* });
+* ```
+*/
+async function retry(fn, options) {
+	const { maxAttempts = 3, delayMs = 100, backoff = (i) => delayMs * Math.pow(2, i) } = options || {};
+	let lastError = null;
+	for (let attempt = 0; attempt < maxAttempts; attempt++) try {
+		return await fn();
+	} catch (error) {
+		lastError = error;
+		if (attempt < maxAttempts - 1) await timeout(backoff(attempt));
+	}
+	throw lastError || /* @__PURE__ */ new Error("Retry failed");
+}
+//#endregion
+export { debounce, defer, idle, once, raf, retry, throttle, timeout };
+
+//# sourceMappingURL=timing.js.map

package/dist/fx/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","names":[],"sources":["../../src/fx/timing.ts"],"sourcesContent":["/**\n * Timing utilities — pure helpers for common async patterns\n * No framework coupling. No lifecycle awareness.\n */\n\nexport interface DebounceOptions {\n  leading?: boolean;\n  trailing?: boolean;\n}\n\nexport interface ThrottleOptions {\n  leading?: boolean;\n  trailing?: boolean;\n}\n\nexport interface RetryOptions {\n  maxAttempts?: number;\n  delayMs?: number;\n  backoff?: (attemptIndex: number) => number;\n}\n\n/**\n * Debounce — delay execution, coalesce rapid calls\n *\n * Useful for: text input, resize, autosave\n *\n * @param fn Function to debounce\n * @param ms Delay in milliseconds\n * @param options trailing (default true), leading\n * @returns Debounced function with cancel() method\n *\n * @example\n * ```ts\n * const save = debounce((text) => api.save(text), 500);\n * input.addEventListener('input', (e) => save(e.target.value));\n * save.cancel(); // stop any pending execution\n * ```\n */\nexport function debounce<T extends (...args: unknown[]) => unknown>(\n  fn: T,\n  ms: number,\n  options?: DebounceOptions\n): T & { cancel(): void } {\n  let timeoutId: NodeJS.Timeout | null = null;\n  const { leading = false, trailing = true } = options || {};\n  let lastArgs: unknown[] | null = null;\n  let lastThis: unknown = null;\n  let lastCallTime = 0;\n\n  const debounced = function (this: unknown, ...args: unknown[]) {\n    const callTime = Date.now();\n    lastArgs = args;\n    // eslint-disable-next-line @typescript-eslint/no-this-alias\n    lastThis = this;\n\n    if (timeoutId !== null) {\n      clearTimeout(timeoutId);\n    }\n\n    if (leading && callTime - lastCallTime >= ms) {\n      fn.apply(this, args);\n      lastCallTime = callTime;\n    }\n\n    if (trailing) {\n      timeoutId = setTimeout(() => {\n        fn.apply(lastThis, lastArgs!);\n        timeoutId = null;\n        lastCallTime = Date.now();\n      }, ms);\n    }\n  };\n\n  debounced.cancel = () => {\n    if (timeoutId !== null) {\n      clearTimeout(timeoutId);\n      timeoutId = null;\n    }\n  };\n\n  return debounced as T & { cancel(): void };\n}\n\n/**\n * Throttle — rate-limit execution, keep first/last\n *\n * Useful for: scroll, mouse move, high-frequency events\n *\n * @param fn Function to throttle\n * @param ms Minimum interval between calls in milliseconds\n * @param options leading (default true), trailing (default true)\n * @returns Throttled function with cancel() method\n *\n * @example\n * ```ts\n * const handleScroll = throttle(updateUI, 100);\n * window.addEventListener('scroll', handleScroll);\n * handleScroll.cancel();\n * ```\n */\nexport function throttle<T extends (...args: unknown[]) => unknown>(\n  fn: T,\n  ms: number,\n  options?: ThrottleOptions\n): T & { cancel(): void } {\n  let lastCallTime = 0;\n  let timeoutId: NodeJS.Timeout | null = null;\n  const { leading = true, trailing = true } = options || {};\n  let lastArgs: unknown[] | null = null;\n  let lastThis: unknown = null;\n\n  const throttled = function (this: unknown, ...args: unknown[]) {\n    const callTime = Date.now();\n    lastArgs = args;\n    // eslint-disable-next-line @typescript-eslint/no-this-alias\n    lastThis = this;\n\n    if (leading && callTime - lastCallTime >= ms) {\n      fn.apply(this, args);\n      lastCallTime = callTime;\n      if (timeoutId !== null) {\n        clearTimeout(timeoutId);\n        timeoutId = null;\n      }\n    } else if (!leading && lastCallTime === 0) {\n      lastCallTime = callTime;\n    }\n\n    if (trailing && timeoutId === null) {\n      timeoutId = setTimeout(\n        () => {\n          fn.apply(lastThis, lastArgs!);\n          lastCallTime = Date.now();\n          timeoutId = null;\n        },\n        ms - (callTime - lastCallTime)\n      );\n    }\n  };\n\n  throttled.cancel = () => {\n    if (timeoutId !== null) {\n      clearTimeout(timeoutId);\n      timeoutId = null;\n    }\n  };\n\n  return throttled as T & { cancel(): void };\n}\n\n/**\n * Once — guard against double execution\n *\n * Useful for: init logic, event safety\n *\n * @param fn Function to call at most once\n * @returns Function that executes fn only on first call\n *\n * @example\n * ```ts\n * const init = once(setup);\n * init(); // runs\n * init(); // does nothing\n * init(); // does nothing\n * ```\n */\nexport function once<T extends (...args: unknown[]) => unknown>(fn: T): T {\n  let called = false;\n  let result: unknown;\n\n  return ((...args: unknown[]) => {\n    if (!called) {\n      called = true;\n      result = fn(...args);\n    }\n    return result;\n  }) as T;\n}\n\n/**\n * Defer — schedule on microtask queue\n *\n * Useful for: run-after-current-stack logic\n * More reliable than setTimeout(..., 0)\n *\n * @param fn Function to defer\n *\n * @example\n * ```ts\n * defer(() => update()); // runs after current stack, before next macrotask\n * ```\n */\nexport function defer(fn: () => void): void {\n  Promise.resolve().then(fn);\n}\n\n/**\n * RAF — coalesce multiple updates into single frame\n *\n * Useful for: animation, layout work, render updates\n *\n * @param fn Function to schedule on next animation frame\n * @returns Function that schedules fn on requestAnimationFrame\n *\n * @example\n * ```ts\n * const update = raf(render);\n * update(); // schedules on next frame\n * update(); // same frame, no duplicate\n * ```\n */\nexport function raf<T extends (...args: unknown[]) => unknown>(fn: T): T {\n  let frameId: number | null = null;\n  let lastArgs: unknown[] | null = null;\n  let lastThis: unknown = null;\n\n  return function (this: unknown, ...args: unknown[]) {\n    lastArgs = args;\n    // eslint-disable-next-line @typescript-eslint/no-this-alias\n    lastThis = this;\n\n    if (frameId === null) {\n      frameId = requestAnimationFrame(() => {\n        fn.apply(lastThis, lastArgs!);\n        frameId = null;\n      });\n    }\n  } as T;\n}\n\n/**\n * Idle — schedule low-priority work\n *\n * Useful for: background prep, non-urgent updates\n * Falls back to setTimeout if requestIdleCallback unavailable\n *\n * @param fn Function to call when idle\n * @param options timeout for fallback\n *\n * @example\n * ```ts\n * idle(() => prefetchData());\n * ```\n */\nexport function idle(fn: () => void, options?: { timeout?: number }): void {\n  if (typeof requestIdleCallback !== 'undefined') {\n    requestIdleCallback(fn, options ? { timeout: options.timeout } : undefined);\n  } else {\n    // Fallback: defer to microtask, then use setTimeout\n    Promise.resolve().then(() => {\n      setTimeout(fn, 0);\n    });\n  }\n}\n\n/**\n * Timeout — Promise-based delay\n *\n * Useful for: readable async code, waiting between retries\n *\n * @param ms Milliseconds to wait\n * @returns Promise that resolves after delay\n *\n * @example\n * ```ts\n * await timeout(300);\n * console.log('300ms later');\n * ```\n */\nexport function timeout(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/**\n * Retry — attempt function with backoff\n *\n * Useful for: network calls, transient failures\n *\n * @param fn Async function to retry\n * @param options maxAttempts, delayMs, backoff function\n * @returns Promise with final result or error\n *\n * @example\n * ```ts\n * const data = await retry(() => fetch(url), {\n *   maxAttempts: 3,\n *   delayMs: 100,\n * });\n * ```\n */\nexport async function retry<T>(\n  fn: () => Promise<T>,\n  options?: RetryOptions\n): Promise<T> {\n  const {\n    maxAttempts = 3,\n    delayMs = 100,\n    backoff = (i: number) => delayMs * Math.pow(2, i),\n  } = options || {};\n\n  let lastError: Error | null = null;\n\n  for (let attempt = 0; attempt < maxAttempts; attempt++) {\n    try {\n      return await fn();\n    } catch (error) {\n      lastError = error as Error;\n      if (attempt < maxAttempts - 1) {\n        const delay = backoff(attempt);\n        await timeout(delay);\n      }\n    }\n  }\n\n  throw lastError || new Error('Retry failed');\n}\n"],"mappings":"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"}