@studiometa/js-toolkit 3.9.0 → 4.0.0-alpha.0

package/dist/services/scroll-progress.js

@@ -0,0 +1,125 @@
+import { getSharedRuntimeSlot } from "../shared-runtime.js";
+import { defaultScheduler } from "../scheduler.js";
+import { createService, perTarget } from "./service.js";
+import { clamp, clamp01 } from "../utils/maths.js";
+import { createServiceMixin } from "./mixin.js";
+import { useWindowSize } from "./resize.js";
+import { getEdges, normalizeOffset } from "./scroll-progress-offset.js";
+import { useWindowScroll } from "./scroll.js";
+//#region src/services/scroll-progress.ts
+const DEFAULT_OFFSET = "start end / end start";
+function progressBetween(current, start, end) {
+	return start === end ? 0 : clamp01((current - start) / (end - start));
+}
+function createScrollProgressService(target, offsetValue) {
+	const offset = normalizeOffset(offsetValue);
+	const props = {
+		startX: 0,
+		startY: 0,
+		endX: 0,
+		endY: 0,
+		currentX: 0,
+		currentY: 0,
+		progressX: 0,
+		progressY: 0
+	};
+	function setCurrent(x, y) {
+		const currentX = clamp(x, props.startX, props.endX);
+		const currentY = clamp(y, props.startY, props.endY);
+		const progressX = progressBetween(currentX, props.startX, props.endX);
+		const progressY = progressBetween(currentY, props.startY, props.endY);
+		const changed = currentX !== props.currentX || currentY !== props.currentY || progressX !== props.progressX || progressY !== props.progressY;
+		props.currentX = currentX;
+		props.currentY = currentY;
+		props.progressX = progressX;
+		props.progressY = progressY;
+		return changed;
+	}
+	function measure() {
+		const { x, y } = useWindowScroll().props();
+		const rect = target.getBoundingClientRect();
+		const [startX, endX] = getEdges({
+			position: rect.left + x,
+			size: rect.width
+		}, {
+			position: 0,
+			size: window.innerWidth
+		}, offset);
+		const [startY, endY] = getEdges({
+			position: rect.top + y,
+			size: rect.height
+		}, {
+			position: 0,
+			size: window.innerHeight
+		}, offset);
+		const changed = startX !== props.startX || startY !== props.startY || endX !== props.endX || endY !== props.endY;
+		props.startX = startX;
+		props.startY = startY;
+		props.endX = endX;
+		props.endY = endY;
+		return setCurrent(x, y) || changed;
+	}
+	return createService({
+		props: () => props,
+		start(emit) {
+			let measureTask = null;
+			const scheduleMeasure = () => {
+				measureTask ??= defaultScheduler.read(() => {
+					measureTask = null;
+					if (measure()) emit(props);
+				});
+			};
+			const unsubscribeScroll = useWindowScroll().subscribe(({ x, y }) => {
+				if (setCurrent(x, y)) emit(props);
+			});
+			const unsubscribeSize = useWindowSize().subscribe(scheduleMeasure);
+			measure();
+			const resizeObserver = new ResizeObserver(scheduleMeasure);
+			resizeObserver.observe(target);
+			const mutationObserver = new MutationObserver(scheduleMeasure);
+			mutationObserver.observe(target, {
+				attributes: true,
+				childList: true,
+				characterData: true,
+				subtree: true
+			});
+			return () => {
+				measureTask?.cancel();
+				measureTask = null;
+				resizeObserver.disconnect();
+				mutationObserver.disconnect();
+				unsubscribeSize();
+				unsubscribeScroll();
+			};
+		}
+	});
+}
+const scrollProgressServices = /* @__PURE__ */ getSharedRuntimeSlot("service:scroll-progress", 1, () => perTarget(createScrollProgressService));
+/**
+* Observe an element's progress through the viewport on both axes.
+*
+* The service is lazy and shared by target plus resolved offset. It measures
+* geometry in the scheduler's read phase and releases its observers and shared
+* source subscriptions with its last subscriber.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/useScrollProgress.html
+*/
+function useScrollProgress(target, { offset = DEFAULT_OFFSET } = {}) {
+	return scrollProgressServices(target, offset);
+}
+/**
+* Subscribe `scrolledInView()` to raw viewport progress for each mount cycle. Returned mutations run through the instance write lane.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+*/
+const withScrollProgress = /* @__PURE__ */ createServiceMixin({
+	hook: "scrolledInView",
+	target: (instance) => instance.$el,
+	defaultImmediate: true,
+	use: (target, options) => useScrollProgress(target, options),
+	handleResult: (instance, result) => {
+		if (typeof result === "function") instance.$write(result);
+	}
+});
+//#endregion
+export { useScrollProgress, withScrollProgress };
+
+//# sourceMappingURL=scroll-progress.js.map

package/dist/services/scroll-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-progress.js","names":[],"sources":["../../src/services/scroll-progress.ts"],"sourcesContent":["import { defaultScheduler, type ScheduledTask } from '../scheduler.js';\nimport { getSharedRuntimeSlot } from '../shared-runtime.js';\nimport { clamp, clamp01 } from '../utils/maths.js';\nimport { createServiceMixin, type ServiceHandles, type ServiceMixinOptions } from './mixin.js';\nimport { getEdges, normalizeOffset, type NormalizedOffset } from './scroll-progress-offset.js';\nimport { useWindowSize } from './resize.js';\nimport { useWindowScroll } from './scroll.js';\nimport { createService, perTarget, type MutableProps, type Service } from './service.js';\n\nconst DEFAULT_OFFSET = 'start end / end start';\n\nexport interface ScrollProgressOptions {\n  /** Two target/viewport edge pairs: `\"start end / end start\"` by default. */\n  offset?: string;\n}\n\n/** The target's element-through-viewport position and progress on both axes. */\nexport interface ScrollProgressProps {\n  readonly startX: number;\n  readonly startY: number;\n  readonly endX: number;\n  readonly endY: number;\n  readonly currentX: number;\n  readonly currentY: number;\n  readonly progressX: number;\n  readonly progressY: number;\n}\n\n/** A DOM mutation returned by `scrolledInView()`, run in the write phase. */\nexport type ScrollProgressRender = () => void;\n\n/** The method `withScrollProgress()` subscribes for the component. */\nexport interface ScrollProgressHook {\n  scrolledInView?(props: ScrollProgressProps): void | ScrollProgressRender;\n}\n\nexport type ScrollProgressMixinOptions = ScrollProgressOptions & ServiceMixinOptions<Element>;\n\nfunction progressBetween(current: number, start: number, end: number): number {\n  return start === end ? 0 : clamp01((current - start) / (end - start));\n}\n\nfunction createScrollProgressService(\n  target: Element,\n  offsetValue: string,\n): Service<ScrollProgressProps> {\n  const offset: NormalizedOffset = normalizeOffset(offsetValue);\n  const props: MutableProps<ScrollProgressProps> = {\n    startX: 0,\n    startY: 0,\n    endX: 0,\n    endY: 0,\n    currentX: 0,\n    currentY: 0,\n    progressX: 0,\n    progressY: 0,\n  };\n\n  function setCurrent(x: number, y: number): boolean {\n    const currentX = clamp(x, props.startX, props.endX);\n    const currentY = clamp(y, props.startY, props.endY);\n    const progressX = progressBetween(currentX, props.startX, props.endX);\n    const progressY = progressBetween(currentY, props.startY, props.endY);\n    const changed =\n      currentX !== props.currentX ||\n      currentY !== props.currentY ||\n      progressX !== props.progressX ||\n      progressY !== props.progressY;\n\n    props.currentX = currentX;\n    props.currentY = currentY;\n    props.progressX = progressX;\n    props.progressY = progressY;\n    return changed;\n  }\n\n  function measure(): boolean {\n    const { x, y } = useWindowScroll().props();\n    const rect = target.getBoundingClientRect();\n    const [startX, endX] = getEdges(\n      { position: rect.left + x, size: rect.width },\n      { position: 0, size: window.innerWidth },\n      offset,\n    );\n    const [startY, endY] = getEdges(\n      { position: rect.top + y, size: rect.height },\n      { position: 0, size: window.innerHeight },\n      offset,\n    );\n    const changed =\n      startX !== props.startX ||\n      startY !== props.startY ||\n      endX !== props.endX ||\n      endY !== props.endY;\n\n    props.startX = startX;\n    props.startY = startY;\n    props.endX = endX;\n    props.endY = endY;\n    return setCurrent(x, y) || changed;\n  }\n\n  return createService({\n    props: () => props,\n    start(emit) {\n      let measureTask: ScheduledTask<void> | null = null;\n      const scheduleMeasure = () => {\n        measureTask ??= defaultScheduler.read(() => {\n          measureTask = null;\n          if (measure()) {\n            emit(props);\n          }\n        });\n      };\n\n      // Start sampled sources before the initial synchronous measurement.\n      const unsubscribeScroll = useWindowScroll().subscribe(({ x, y }) => {\n        if (setCurrent(x, y)) {\n          emit(props);\n        }\n      });\n      const unsubscribeSize = useWindowSize().subscribe(scheduleMeasure);\n      measure();\n\n      // MutationObserver catches geometry changes that do not resize the target box.\n      const resizeObserver = new ResizeObserver(scheduleMeasure);\n      resizeObserver.observe(target);\n      const mutationObserver = new MutationObserver(scheduleMeasure);\n      mutationObserver.observe(target, {\n        attributes: true,\n        childList: true,\n        characterData: true,\n        subtree: true,\n      });\n\n      return () => {\n        measureTask?.cancel();\n        measureTask = null;\n        resizeObserver.disconnect();\n        mutationObserver.disconnect();\n        unsubscribeSize();\n        unsubscribeScroll();\n      };\n    },\n  });\n}\n\nconst scrollProgressServices = /* @__PURE__ */ getSharedRuntimeSlot(\n  'service:scroll-progress',\n  1,\n  () => perTarget(createScrollProgressService),\n);\n\n/**\n * Observe an element's progress through the viewport on both axes.\n *\n * The service is lazy and shared by target plus resolved offset. It measures\n * geometry in the scheduler's read phase and releases its observers and shared\n * source subscriptions with its last subscriber.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/useScrollProgress.html\n */\nexport function useScrollProgress(\n  target: Element,\n  { offset = DEFAULT_OFFSET }: ScrollProgressOptions = {},\n): Service<ScrollProgressProps> {\n  return scrollProgressServices(target, offset);\n}\n\n/**\n * Subscribe `scrolledInView()` to raw viewport progress for each mount cycle. Returned mutations run through the instance write lane.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html\n */\nexport const withScrollProgress = /* @__PURE__ */ createServiceMixin<\n  ScrollProgressHook & ServiceHandles<'scrolledInView'>,\n  Element,\n  ScrollProgressOptions\n>({\n  hook: 'scrolledInView',\n  target: (instance) => instance.$el,\n  defaultImmediate: true,\n  use: (target, options) => useScrollProgress(target, options),\n  handleResult: (instance, result) => {\n    if (typeof result === 'function') {\n      instance.$write(result as ScrollProgressRender);\n    }\n  },\n});\n"],"mappings":"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"}

package/dist/services/scroll.d.ts

@@ -0,0 +1,47 @@
+import { Service } from "./service.js";
+import { ServiceHandles, ServiceMixin, ServiceMixinOptions } from "./mixin.js";
+//#region src/services/scroll.d.ts
+/** Anything that scrolls: the window, or an element with an overflow. */
+type ScrollTarget = Element | Window;
+/** Axis direction: `1` forward, `-1` backward, or `0` unchanged. */
+type ScrollDirection = -1 | 0 | 1;
+/** Current scroll state and movement. */
+interface ScrollProps {
+  readonly x: number;
+  readonly y: number;
+  /** Movement since the previous update. */
+  readonly deltaX: number;
+  readonly deltaY: number;
+  /** Furthest scrollable position, `0` when the axis does not scroll. */
+  readonly maxX: number;
+  readonly maxY: number;
+  /** Progress from the logical start, from `0` to `1`. A fixed axis reports `0`. */
+  readonly progressX: number;
+  readonly progressY: number;
+  readonly directionX: ScrollDirection;
+  readonly directionY: ScrollDirection;
+  /** Whether the target is moving, including momentum, smooth scroll, and snap settling. */
+  readonly isScrolling: boolean;
+}
+/**
+ * Use one scroll service per target. Defaults to the window.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/useScroll.html
+ */
+declare function useScroll(target?: ScrollTarget): Service<ScrollProps>;
+/**
+ * Use the scroll service for the window.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/useWindowScroll.html
+ */
+declare function useWindowScroll(): Service<ScrollProps>;
+/** The method `withScroll()` subscribes for the component. */
+interface ScrollHook {
+  scrolled?(props: ScrollProps): void;
+}
+type ScrollMixinOptions = ServiceMixinOptions<ScrollTarget>;
+/**
+ * Subscribe `scrolled()` for each mount cycle. The window is the default target.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+ */
+declare const withScroll: ServiceMixin<ScrollHook & ServiceHandles<"scrolled">, ScrollTarget, object>;
+//#endregion
+export { ScrollDirection, ScrollHook, ScrollMixinOptions, ScrollProps, ScrollTarget, useScroll, useWindowScroll, withScroll };

package/dist/services/scroll.js

@@ -0,0 +1,170 @@
+import { getSharedRuntimeSlot } from "../shared-runtime.js";
+import { defaultScheduler } from "../scheduler.js";
+import { createService, perTarget } from "./service.js";
+import { createServiceMixin } from "./mixin.js";
+//#region src/services/scroll.ts
+/** Quiet-period fallback for browsers without `scrollend`. */
+const SCROLL_END_FALLBACK_DELAY = 120;
+const supportsScrollEnd = /* @__PURE__ */ (() => typeof window !== "undefined" && "onscrollend" in window)();
+/** The element whose content decides how far the target can scroll. */
+function scrollerOf(target) {
+	if (target instanceof Window) return document.scrollingElement ?? document.documentElement;
+	return target;
+}
+/**
+* Where the target stands and how far it can go. The window scrolls the
+* document, so its maximums come from the scrolling element rather than from
+* the window itself.
+*/
+function measure(target) {
+	if (target instanceof Window) {
+		const scrollingElement = scrollerOf(target);
+		return {
+			x: target.scrollX,
+			y: target.scrollY,
+			maxX: Math.max(0, scrollingElement.scrollWidth - target.innerWidth),
+			maxY: Math.max(0, scrollingElement.scrollHeight - target.innerHeight)
+		};
+	}
+	return {
+		x: target.scrollLeft,
+		y: target.scrollTop,
+		maxX: Math.max(0, target.scrollWidth - target.clientWidth),
+		maxY: Math.max(0, target.scrollHeight - target.clientHeight)
+	};
+}
+/** Resolve progress from the logical start, including negative RTL `scrollLeft`. */
+function directionOf(delta) {
+	if (delta > 0) return 1;
+	if (delta < 0) return -1;
+	return 0;
+}
+function progressFor(position, max) {
+	return max <= 0 ? 0 : Math.abs(position) / max;
+}
+function createScrollService(target) {
+	const initial = measure(target);
+	const props = {
+		x: initial.x,
+		y: initial.y,
+		deltaX: 0,
+		deltaY: 0,
+		maxX: initial.maxX,
+		maxY: initial.maxY,
+		progressX: progressFor(initial.x, initial.maxX),
+		progressY: progressFor(initial.y, initial.maxY),
+		directionX: 0,
+		directionY: 0,
+		isScrolling: false
+	};
+	function update() {
+		const lastX = props.x;
+		const lastY = props.y;
+		const { x, y, maxX, maxY } = measure(target);
+		props.x = x;
+		props.y = y;
+		props.deltaX = x - lastX;
+		props.deltaY = y - lastY;
+		props.maxX = maxX;
+		props.maxY = maxY;
+		props.progressX = progressFor(x, maxX);
+		props.progressY = progressFor(y, maxY);
+		props.directionX = directionOf(props.deltaX);
+		props.directionY = directionOf(props.deltaY);
+		return props;
+	}
+	/** Re-measure at startup and reset movement from the previous run. */
+	function resync() {
+		update();
+		props.deltaX = 0;
+		props.deltaY = 0;
+		props.directionX = 0;
+		props.directionY = 0;
+		return props;
+	}
+	return createService({
+		props: () => props,
+		start(emit) {
+			let task = null;
+			let fallbackTimer;
+			const flush = () => {
+				task ??= defaultScheduler.read(() => {
+					task = null;
+					emit(update());
+				});
+			};
+			const onScrollEnd = () => {
+				props.isScrolling = false;
+				flush();
+			};
+			const onScroll = () => {
+				props.isScrolling = true;
+				if (!supportsScrollEnd) {
+					clearTimeout(fallbackTimer);
+					fallbackTimer = setTimeout(onScrollEnd, SCROLL_END_FALLBACK_DELAY);
+				}
+				flush();
+			};
+			const onResize = () => flush();
+			/** Observe child boxes and child-list changes because content can change extents without resizing the container. */
+			const scroller = scrollerOf(target);
+			const refreshExtents = () => {
+				const { maxX, maxY } = measure(target);
+				if (maxX !== props.maxX || maxY !== props.maxY) flush();
+			};
+			const contentObserver = new ResizeObserver(refreshExtents);
+			const observeContent = () => {
+				contentObserver.disconnect();
+				contentObserver.observe(scroller);
+				for (const child of scroller.children) contentObserver.observe(child);
+			};
+			const childrenObserver = new MutationObserver(observeContent);
+			resync();
+			target.addEventListener("scroll", onScroll, { passive: true });
+			if (supportsScrollEnd) target.addEventListener("scrollend", onScrollEnd);
+			window.addEventListener("resize", onResize, { passive: true });
+			observeContent();
+			childrenObserver.observe(scroller, { childList: true });
+			return () => {
+				task?.cancel();
+				task = null;
+				clearTimeout(fallbackTimer);
+				contentObserver.disconnect();
+				childrenObserver.disconnect();
+				props.isScrolling = false;
+				target.removeEventListener("scroll", onScroll);
+				target.removeEventListener("scrollend", onScrollEnd);
+				window.removeEventListener("resize", onResize);
+			};
+		}
+	});
+}
+const scrollServices = /* @__PURE__ */ getSharedRuntimeSlot("service:scroll", 1, () => perTarget(createScrollService));
+/**
+* Use one scroll service per target. Defaults to the window.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/useScroll.html
+*/
+function useScroll(target = window) {
+	if (target === document.scrollingElement || target === document.documentElement) return scrollServices(window);
+	return scrollServices(target);
+}
+/**
+* Use the scroll service for the window.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/useWindowScroll.html
+*/
+function useWindowScroll() {
+	return scrollServices(window);
+}
+/**
+* Subscribe `scrolled()` for each mount cycle. The window is the default target.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+*/
+const withScroll = /* @__PURE__ */ createServiceMixin({
+	hook: "scrolled",
+	target: () => window,
+	use: (target) => useScroll(target)
+});
+//#endregion
+export { useScroll, useWindowScroll, withScroll };
+
+//# sourceMappingURL=scroll.js.map

package/dist/services/scroll.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll.js","names":[],"sources":["../../src/services/scroll.ts"],"sourcesContent":["import { defaultScheduler, type ScheduledTask } from '../scheduler.js';\nimport { getSharedRuntimeSlot } from '../shared-runtime.js';\nimport { createServiceMixin, type ServiceHandles, type ServiceMixinOptions } from './mixin.js';\nimport { createService, perTarget, type MutableProps, type Service } from './service.js';\n\n/** Anything that scrolls: the window, or an element with an overflow. */\nexport type ScrollTarget = Element | Window;\n\n/** Axis direction: `1` forward, `-1` backward, or `0` unchanged. */\nexport type ScrollDirection = -1 | 0 | 1;\n\n/** Current scroll state and movement. */\nexport interface ScrollProps {\n  readonly x: number;\n  readonly y: number;\n  /** Movement since the previous update. */\n  readonly deltaX: number;\n  readonly deltaY: number;\n  /** Furthest scrollable position, `0` when the axis does not scroll. */\n  readonly maxX: number;\n  readonly maxY: number;\n  /** Progress from the logical start, from `0` to `1`. A fixed axis reports `0`. */\n  readonly progressX: number;\n  readonly progressY: number;\n  readonly directionX: ScrollDirection;\n  readonly directionY: ScrollDirection;\n  /** Whether the target is moving, including momentum, smooth scroll, and snap settling. */\n  readonly isScrolling: boolean;\n}\n\n/** Quiet-period fallback for browsers without `scrollend`. */\nconst SCROLL_END_FALLBACK_DELAY = 120;\n\nconst supportsScrollEnd = /* @__PURE__ */ (() =>\n  typeof window !== 'undefined' && 'onscrollend' in window)();\n\n/** The element whose content decides how far the target can scroll. */\nfunction scrollerOf(target: ScrollTarget): Element {\n  if (target instanceof Window) {\n    return document.scrollingElement ?? document.documentElement;\n  }\n  return target;\n}\n\n/**\n * Where the target stands and how far it can go. The window scrolls the\n * document, so its maximums come from the scrolling element rather than from\n * the window itself.\n */\nfunction measure(target: ScrollTarget) {\n  if (target instanceof Window) {\n    const scrollingElement = scrollerOf(target);\n    return {\n      x: target.scrollX,\n      y: target.scrollY,\n      // Classic scrollbars can make `scrollWidth - innerWidth` negative.\n      maxX: Math.max(0, scrollingElement.scrollWidth - target.innerWidth),\n      maxY: Math.max(0, scrollingElement.scrollHeight - target.innerHeight),\n    };\n  }\n  return {\n    x: target.scrollLeft,\n    y: target.scrollTop,\n    // Clamp fractional-zoom rounding.\n    maxX: Math.max(0, target.scrollWidth - target.clientWidth),\n    maxY: Math.max(0, target.scrollHeight - target.clientHeight),\n  };\n}\n\n/** Resolve progress from the logical start, including negative RTL `scrollLeft`. */\nfunction directionOf(delta: number): ScrollDirection {\n  if (delta > 0) return 1;\n  if (delta < 0) return -1;\n  return 0;\n}\n\nfunction progressFor(position: number, max: number): number {\n  // A non-positive extent is fixed at the start and must not produce `-0`.\n  return max <= 0 ? 0 : Math.abs(position) / max;\n}\n\nfunction createScrollService(target: ScrollTarget): Service<ScrollProps> {\n  const initial = measure(target);\n  const props: MutableProps<ScrollProps> = {\n    x: initial.x,\n    y: initial.y,\n    deltaX: 0,\n    deltaY: 0,\n    maxX: initial.maxX,\n    maxY: initial.maxY,\n    progressX: progressFor(initial.x, initial.maxX),\n    progressY: progressFor(initial.y, initial.maxY),\n    directionX: 0,\n    directionY: 0,\n    isScrolling: false,\n  };\n\n  function update(): ScrollProps {\n    const lastX = props.x;\n    const lastY = props.y;\n    const { x, y, maxX, maxY } = measure(target);\n\n    props.x = x;\n    props.y = y;\n    props.deltaX = x - lastX;\n    props.deltaY = y - lastY;\n    props.maxX = maxX;\n    props.maxY = maxY;\n    props.progressX = progressFor(x, maxX);\n    props.progressY = progressFor(y, maxY);\n    props.directionX = directionOf(props.deltaX);\n    props.directionY = directionOf(props.deltaY);\n\n    return props;\n  }\n\n  /** Re-measure at startup and reset movement from the previous run. */\n  function resync(): ScrollProps {\n    update();\n    props.deltaX = 0;\n    props.deltaY = 0;\n    props.directionX = 0;\n    props.directionY = 0;\n    return props;\n  }\n\n  return createService<ScrollProps>({\n    props: () => props,\n    start(emit) {\n      let task: ScheduledTask<void> | null = null;\n      let fallbackTimer: ReturnType<typeof setTimeout> | undefined;\n\n      const flush = () => {\n        // Coalesce measurements into the scheduler read phase.\n        task ??= defaultScheduler.read(() => {\n          task = null;\n          emit(update());\n        });\n      };\n\n      const onScrollEnd = () => {\n        props.isScrolling = false;\n        // Emit the settled state even when position is unchanged.\n        flush();\n      };\n\n      const onScroll = () => {\n        props.isScrolling = true;\n        if (!supportsScrollEnd) {\n          clearTimeout(fallbackTimer);\n          fallbackTimer = setTimeout(onScrollEnd, SCROLL_END_FALLBACK_DELAY);\n        }\n        flush();\n      };\n\n      // Resize changes extents without entering the scrolling state.\n      const onResize = () => flush();\n\n      /** Observe child boxes and child-list changes because content can change extents without resizing the container. */\n      const scroller = scrollerOf(target);\n      const refreshExtents = () => {\n        const { maxX, maxY } = measure(target);\n        if (maxX !== props.maxX || maxY !== props.maxY) {\n          flush();\n        }\n      };\n      const contentObserver = new ResizeObserver(refreshExtents);\n      const observeContent = () => {\n        contentObserver.disconnect();\n        contentObserver.observe(scroller);\n        for (const child of scroller.children) {\n          contentObserver.observe(child);\n        }\n      };\n      const childrenObserver = new MutationObserver(observeContent);\n\n      // Refresh extents before immediate delivery.\n      resync();\n      // `scroll` does not bubble; listen on the observed scroller.\n      target.addEventListener('scroll', onScroll, { passive: true });\n      if (supportsScrollEnd) {\n        target.addEventListener('scrollend', onScrollEnd);\n      }\n      window.addEventListener('resize', onResize, { passive: true });\n      observeContent();\n      childrenObserver.observe(scroller, { childList: true });\n\n      return () => {\n        task?.cancel();\n        task = null;\n        clearTimeout(fallbackTimer);\n        contentObserver.disconnect();\n        childrenObserver.disconnect();\n        props.isScrolling = false;\n        target.removeEventListener('scroll', onScroll);\n        target.removeEventListener('scrollend', onScrollEnd);\n        window.removeEventListener('resize', onResize);\n      };\n    },\n  });\n}\n\nconst scrollServices = /* @__PURE__ */ getSharedRuntimeSlot('service:scroll', 1, () =>\n  perTarget(createScrollService),\n);\n\n/**\n * Use one scroll service per target. Defaults to the window.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/useScroll.html\n */\nexport function useScroll(target: ScrollTarget = window): Service<ScrollProps> {\n  // The document scrolling element uses the window service.\n  if (target === document.scrollingElement || target === document.documentElement) {\n    return scrollServices(window);\n  }\n  return scrollServices(target);\n}\n\n/**\n * Use the scroll service for the window.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/useWindowScroll.html\n */\nexport function useWindowScroll(): Service<ScrollProps> {\n  return scrollServices(window);\n}\n\n/** The method `withScroll()` subscribes for the component. */\nexport interface ScrollHook {\n  scrolled?(props: ScrollProps): void;\n}\n\nexport type ScrollMixinOptions = ServiceMixinOptions<ScrollTarget>;\n\n/**\n * Subscribe `scrolled()` for each mount cycle. The window is the default target.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html\n */\nexport const withScroll = /* @__PURE__ */ createServiceMixin<\n  ScrollHook & ServiceHandles<'scrolled'>,\n  ScrollTarget\n>({\n  hook: 'scrolled',\n  target: () => window,\n  use: (target) => useScroll(target),\n});\n"],"mappings":"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"}

package/dist/services/service.d.ts

@@ -0,0 +1,60 @@
+//#region src/services/service.d.ts
+/** Release one subscription. Services start with their first subscriber and stop with their last. */
+type Unsubscribe = () => void;
+/** A service callback with a service-specific return type. */
+type ServiceCallback<T, R = void> = (props: T) => R;
+/** Subscription options. */
+interface SubscribeOptions {
+  /** Deliver current props immediately when the source has an observed value. */
+  immediate?: boolean;
+}
+interface Service<T, R = void> {
+  /**
+   * Subscribe to the service, starting it if it was not running.
+   *
+   * @returns Unsubscribe. The service stops with its last subscriber.
+   */
+  subscribe(callback: ServiceCallback<T, R>, options?: SubscribeOptions): Unsubscribe;
+  /**
+   * Return current props without subscribing. The shared object can be overwritten on the next update; copy values that must persist.
+   */
+  props(): T;
+}
+/**
+ * A service's own view of its props: the same shape, writable, because the
+ * service is the one that fills it in.
+ */
+type MutableProps<T> = { -readonly [K in keyof T]: T[K]; };
+interface ServiceDefinition<T> {
+  props: () => T;
+  /** Whether `props()` contains an observed value. Defaults to `true`. */
+  hasProps?: () => boolean;
+  /**
+   * Start observing, returning the teardown.
+   *
+   * `emit` fans the props out to every subscriber. What a subscriber returns
+   * is between it and its service — `useRaf()` collects render functions
+   * that way — so nothing comes back here.
+   */
+  start: (emit: (props: T) => void) => Unsubscribe;
+}
+/**
+ * Build a service from its definition.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/createService.html
+ */
+declare function createService<T, R = void>({ props, start, hasProps }: ServiceDefinition<T>): Service<T, R>;
+/**
+ * Key plain-data arguments by what they mean, independently of how they were written.
+ * @internal
+ */
+declare function stableKey(...args: unknown[]): string;
+/**
+ * Create one weakly held service per target and argument key.
+ *
+ * @param create Called once per target and argument pair.
+ * @param keyOf Serializes arguments. Defaults to {@link stableKey}.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/perTarget.html
+ */
+declare function perTarget<Target extends WeakKey, Args extends unknown[], T, R = void>(create: (target: Target, ...args: Args) => Service<T, R>, keyOf?: (...args: Args) => string): (target: Target, ...args: Args) => Service<T, R>;
+//#endregion
+export { MutableProps, Service, ServiceCallback, ServiceDefinition, SubscribeOptions, Unsubscribe, createService, perTarget, stableKey };

package/dist/services/service.js

@@ -0,0 +1,110 @@
+import { isolateCallbackFailure } from "../diagnostics.js";
+//#region src/services/service.ts
+/**
+* Build a service from its definition.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/createService.html
+*/
+function createService({ props, start, hasProps }) {
+	const subscriptions = /* @__PURE__ */ new Set();
+	let state = "idle";
+	let stop = null;
+	function emit(current) {
+		const batch = [...subscriptions];
+		for (const subscription of batch) {
+			if (!subscription.isActive) continue;
+			isolateCallbackFailure("callback.service-failed", "A service subscriber failed.", () => subscription.callback(current));
+		}
+	}
+	return {
+		props,
+		subscribe(callback, { immediate = false } = {}) {
+			const subscription = {
+				callback,
+				isActive: true
+			};
+			subscriptions.add(subscription);
+			if (state === "idle") {
+				state = "starting";
+				try {
+					stop = start(emit);
+					state = "running";
+				} catch (error) {
+					for (const joined of subscriptions) joined.isActive = false;
+					subscriptions.clear();
+					stop = null;
+					state = "idle";
+					throw error;
+				}
+			}
+			if (immediate && (hasProps?.() ?? true)) isolateCallbackFailure("callback.service-failed", "An immediate service subscriber failed.", () => callback(props()));
+			return () => {
+				if (!subscription.isActive) return;
+				subscription.isActive = false;
+				subscriptions.delete(subscription);
+				if (subscriptions.size > 0) return;
+				if (state !== "running") return;
+				const release = stop;
+				stop = null;
+				state = "idle";
+				release?.();
+			};
+		}
+	};
+}
+/**
+* Serialize a value so that two spellings of one observation write one string.
+*
+* `JSON.stringify()` alone put spelling in the identity: `{ axis, inertia }`
+* and `{ inertia, axis }` describe the same drag and bought two services —
+* two pointer listener sets on one element. Object keys are therefore sorted,
+* and a key holding `undefined` is dropped, because naming an option without a
+* value is the same request as not naming it. Arrays keep their order: a
+* threshold list is ordered data, not a record.
+*
+* It covers what services are keyed on — plain objects, arrays, primitives and
+* `undefined`. An object the platform owns has no own enumerable keys and
+* serializes as `{}`, which is why a service holding one, such as the
+* `IntersectionObserver` root, gives it a stable identity before keying it.
+*/
+function stableStringify(value) {
+	if (value === void 0) return "undefined";
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+	const record = value;
+	return `{${Object.keys(record).sort().filter((key) => record[key] !== void 0).map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+}
+/**
+* Key plain-data arguments by what they mean, independently of how they were written.
+* @internal
+*/
+function stableKey(...args) {
+	return stableStringify(args);
+}
+/**
+* Create one weakly held service per target and argument key.
+*
+* @param create Called once per target and argument pair.
+* @param keyOf Serializes arguments. Defaults to {@link stableKey}.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/perTarget.html
+*/
+function perTarget(create, keyOf = stableKey) {
+	const services = /* @__PURE__ */ new WeakMap();
+	return (target, ...args) => {
+		let byArgs = services.get(target);
+		if (!byArgs) {
+			byArgs = /* @__PURE__ */ new Map();
+			services.set(target, byArgs);
+		}
+		const key = keyOf(...args);
+		let service = byArgs.get(key);
+		if (!service) {
+			service = create(target, ...args);
+			byArgs.set(key, service);
+		}
+		return service;
+	};
+}
+//#endregion
+export { createService, perTarget, stableKey };
+
+//# sourceMappingURL=service.js.map

package/dist/services/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","names":[],"sources":["../../src/services/service.ts"],"sourcesContent":["import { isolateCallbackFailure } from '../diagnostics.js';\n\n/** Release one subscription. Services start with their first subscriber and stop with their last. */\nexport type Unsubscribe = () => void;\n\n/** A service callback with a service-specific return type. */\nexport type ServiceCallback<T, R = void> = (props: T) => R;\n\n/** Subscription options. */\nexport interface SubscribeOptions {\n  /** Deliver current props immediately when the source has an observed value. */\n  immediate?: boolean;\n}\n\nexport interface Service<T, R = void> {\n  /**\n   * Subscribe to the service, starting it if it was not running.\n   *\n   * @returns Unsubscribe. The service stops with its last subscriber.\n   */\n  subscribe(callback: ServiceCallback<T, R>, options?: SubscribeOptions): Unsubscribe;\n  /**\n   * Return current props without subscribing. The shared object can be overwritten on the next update; copy values that must persist.\n   */\n  props(): T;\n}\n\n/**\n * A service's own view of its props: the same shape, writable, because the\n * service is the one that fills it in.\n */\nexport type MutableProps<T> = { -readonly [K in keyof T]: T[K] };\n\nexport interface ServiceDefinition<T> {\n  props: () => T;\n  /** Whether `props()` contains an observed value. Defaults to `true`. */\n  hasProps?: () => boolean;\n  /**\n   * Start observing, returning the teardown.\n   *\n   * `emit` fans the props out to every subscriber. What a subscriber returns\n   * is between it and its service — `useRaf()` collects render functions\n   * that way — so nothing comes back here.\n   */\n  start: (emit: (props: T) => void) => Unsubscribe;\n}\n\n/** One independently owned subscription. */\ninterface Subscription<T, R> {\n  callback: ServiceCallback<T, R>;\n  /** Prevent delivery after unsubscribe during a snapshot iteration. */\n  isActive: boolean;\n}\n\n/**\n * Build a service from its definition.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/createService.html\n */\nexport function createService<T, R = void>({\n  props,\n  start,\n  hasProps,\n}: ServiceDefinition<T>): Service<T, R> {\n  const subscriptions = new Set<Subscription<T, R>>();\n  let state: 'idle' | 'starting' | 'running' = 'idle';\n  let stop: Unsubscribe | null = null;\n\n  function emit(current: T): void {\n    // Snapshot delivery excludes later additions; `isActive` handles removals.\n    const batch = [...subscriptions];\n    for (const subscription of batch) {\n      if (!subscription.isActive) {\n        continue;\n      }\n      isolateCallbackFailure('callback.service-failed', 'A service subscriber failed.', () =>\n        subscription.callback(current),\n      );\n    }\n  }\n\n  return {\n    props,\n    subscribe(callback, { immediate = false } = {}) {\n      const subscription: Subscription<T, R> = { callback, isActive: true };\n      subscriptions.add(subscription);\n      if (state === 'idle') {\n        // Mark startup first so reentrant subscriptions join this run.\n        state = 'starting';\n        try {\n          stop = start(emit);\n          state = 'running';\n        } catch (error) {\n          // Roll back every subscription that joined the failed startup.\n          for (const joined of subscriptions) {\n            joined.isActive = false;\n          }\n          subscriptions.clear();\n          stop = null;\n          state = 'idle';\n          throw error;\n        }\n      }\n      // Deliver after startup, when props are current, and only to the new subscriber.\n      if (immediate && (hasProps?.() ?? true)) {\n        // Keep `subscribe()` successful so the caller receives its unsubscribe.\n        isolateCallbackFailure(\n          'callback.service-failed',\n          'An immediate service subscriber failed.',\n          () => callback(props()),\n        );\n      }\n      return () => {\n        // Unsubscribe is idempotent.\n        if (!subscription.isActive) {\n          return;\n        }\n        // Clear activity before removal so an active snapshot skips it.\n        subscription.isActive = false;\n        subscriptions.delete(subscription);\n        if (subscriptions.size > 0) {\n          return;\n        }\n        if (state !== 'running') {\n          return;\n        }\n        const release = stop;\n        stop = null;\n        state = 'idle';\n        release?.();\n      };\n    },\n  };\n}\n\n/**\n * Serialize a value so that two spellings of one observation write one string.\n *\n * `JSON.stringify()` alone put spelling in the identity: `{ axis, inertia }`\n * and `{ inertia, axis }` describe the same drag and bought two services —\n * two pointer listener sets on one element. Object keys are therefore sorted,\n * and a key holding `undefined` is dropped, because naming an option without a\n * value is the same request as not naming it. Arrays keep their order: a\n * threshold list is ordered data, not a record.\n *\n * It covers what services are keyed on — plain objects, arrays, primitives and\n * `undefined`. An object the platform owns has no own enumerable keys and\n * serializes as `{}`, which is why a service holding one, such as the\n * `IntersectionObserver` root, gives it a stable identity before keying it.\n */\nfunction stableStringify(value: unknown): string {\n  // `JSON.stringify(undefined)` returns no string at all, so name it here.\n  if (value === undefined) {\n    return 'undefined';\n  }\n  if (value === null || typeof value !== 'object') {\n    return JSON.stringify(value);\n  }\n  if (Array.isArray(value)) {\n    return `[${value.map((item) => stableStringify(item)).join(',')}]`;\n  }\n  const record = value as Record<string, unknown>;\n  const entries = Object.keys(record)\n    .sort()\n    .filter((key) => record[key] !== undefined)\n    .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`);\n  return `{${entries.join(',')}}`;\n}\n\n/**\n * Key plain-data arguments by what they mean, independently of how they were written.\n * @internal\n */\nexport function stableKey(...args: unknown[]): string {\n  return stableStringify(args);\n}\n\n/**\n * Create one weakly held service per target and argument key.\n *\n * @param create Called once per target and argument pair.\n * @param keyOf Serializes arguments. Defaults to {@link stableKey}.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/perTarget.html\n */\nexport function perTarget<Target extends WeakKey, Args extends unknown[], T, R = void>(\n  create: (target: Target, ...args: Args) => Service<T, R>,\n  keyOf: (...args: Args) => string = stableKey,\n): (target: Target, ...args: Args) => Service<T, R> {\n  const services = new WeakMap<Target, Map<string, Service<T, R>>>();\n  return (target, ...args) => {\n    let byArgs = services.get(target);\n    if (!byArgs) {\n      byArgs = new Map();\n      services.set(target, byArgs);\n    }\n    const key = keyOf(...args);\n    let service = byArgs.get(key);\n    if (!service) {\n      service = create(target, ...args);\n      byArgs.set(key, service);\n    }\n    return service;\n  };\n}\n"],"mappings":";;;;;;AA0DA,SAAgB,cAA2B,EACzC,OACA,OACA,YACsC;CACtC,MAAM,gCAAgB,IAAI,IAAwB;CAClD,IAAI,QAAyC;CAC7C,IAAI,OAA2B;CAE/B,SAAS,KAAK,SAAkB;EAE9B,MAAM,QAAQ,CAAC,GAAG,aAAa;EAC/B,KAAK,MAAM,gBAAgB,OAAO;GAChC,IAAI,CAAC,aAAa,UAChB;GAEF,uBAAuB,2BAA2B,sCAChD,aAAa,SAAS,OAAO,CAC/B;EACF;CACF;CAEA,OAAO;EACL;EACA,UAAU,UAAU,EAAE,YAAY,UAAU,CAAC,GAAG;GAC9C,MAAM,eAAmC;IAAE;IAAU,UAAU;GAAK;GACpE,cAAc,IAAI,YAAY;GAC9B,IAAI,UAAU,QAAQ;IAEpB,QAAQ;IACR,IAAI;KACF,OAAO,MAAM,IAAI;KACjB,QAAQ;IACV,SAAS,OAAO;KAEd,KAAK,MAAM,UAAU,eACnB,OAAO,WAAW;KAEpB,cAAc,MAAM;KACpB,OAAO;KACP,QAAQ;KACR,MAAM;IACR;GACF;GAEA,IAAI,cAAc,WAAW,KAAK,OAEhC,uBACE,2BACA,iDACM,SAAS,MAAM,CAAC,CACxB;GAEF,aAAa;IAEX,IAAI,CAAC,aAAa,UAChB;IAGF,aAAa,WAAW;IACxB,cAAc,OAAO,YAAY;IACjC,IAAI,cAAc,OAAO,GACvB;IAEF,IAAI,UAAU,WACZ;IAEF,MAAM,UAAU;IAChB,OAAO;IACP,QAAQ;IACR,UAAU;GACZ;EACF;CACF;AACF;;;;;;;;;;;;;;;;AAiBA,SAAS,gBAAgB,OAAwB;CAE/C,IAAI,UAAU,KAAA,GACZ,OAAO;CAET,IAAI,UAAU,QAAQ,OAAO,UAAU,UACrC,OAAO,KAAK,UAAU,KAAK;CAE7B,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,IAAI,MAAM,KAAK,SAAS,gBAAgB,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE;CAElE,MAAM,SAAS;CAKf,OAAO,IAJS,OAAO,KAAK,MAAM,CAAC,CAChC,KAAK,CAAC,CACN,QAAQ,QAAQ,OAAO,SAAS,KAAA,CAAS,CAAC,CAC1C,KAAK,QAAQ,GAAG,KAAK,UAAU,GAAG,EAAE,GAAG,gBAAgB,OAAO,IAAI,GACpD,CAAC,CAAC,KAAK,GAAG,EAAE;AAC/B;;;;;AAMA,SAAgB,UAAU,GAAG,MAAyB;CACpD,OAAO,gBAAgB,IAAI;AAC7B;;;;;;;;AASA,SAAgB,UACd,QACA,QAAmC,WACe;CAClD,MAAM,2BAAW,IAAI,QAA4C;CACjE,QAAQ,QAAQ,GAAG,SAAS;EAC1B,IAAI,SAAS,SAAS,IAAI,MAAM;EAChC,IAAI,CAAC,QAAQ;GACX,yBAAS,IAAI,IAAI;GACjB,SAAS,IAAI,QAAQ,MAAM;EAC7B;EACA,MAAM,MAAM,MAAM,GAAG,IAAI;EACzB,IAAI,UAAU,OAAO,IAAI,GAAG;EAC5B,IAAI,CAAC,SAAS;GACZ,UAAU,OAAO,QAAQ,GAAG,IAAI;GAChC,OAAO,IAAI,KAAK,OAAO;EACzB;EACA,OAAO;CACT;AACF"}

package/dist/services/toggle.d.ts

@@ -0,0 +1,20 @@
+import { Unsubscribe } from "./service.js";
+//#region src/services/toggle.d.ts
+/** A subscription that the caller can start and stop. Methods are bound. */
+interface Toggle {
+  /** Whether the subscription is running. */
+  readonly isActive: boolean;
+  /** Subscribe now, unless it is subscribed already. */
+  start: () => void;
+  /** Release the subscription, if it has one. */
+  stop: () => void;
+}
+/**
+ * Make an unsubscribe-producing operation suspendable and resumable.
+ *
+ * `start()` and `stop()` are idempotent.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/toggle.html
+ */
+declare function toggle(subscribe: () => Unsubscribe): Toggle;
+//#endregion
+export { Toggle, toggle };

package/dist/services/toggle.js

@@ -0,0 +1,42 @@
+//#region src/services/toggle.ts
+/**
+* Make an unsubscribe-producing operation suspendable and resumable.
+*
+* `start()` and `stop()` are idempotent.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/toggle.html
+*/
+function toggle(subscribe) {
+	let unsubscribe = null;
+	let isStarting = false;
+	let stopPending = false;
+	return {
+		get isActive() {
+			return unsubscribe !== null || isStarting && !stopPending;
+		},
+		start: () => {
+			if (unsubscribe !== null || isStarting) return;
+			isStarting = true;
+			try {
+				const cleanup = subscribe();
+				if (stopPending) cleanup();
+				else unsubscribe = cleanup;
+			} finally {
+				isStarting = false;
+				stopPending = false;
+			}
+		},
+		stop: () => {
+			if (isStarting) {
+				stopPending = true;
+				return;
+			}
+			const cleanup = unsubscribe;
+			unsubscribe = null;
+			cleanup?.();
+		}
+	};
+}
+//#endregion
+export { toggle };
+
+//# sourceMappingURL=toggle.js.map

package/dist/services/toggle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toggle.js","names":[],"sources":["../../src/services/toggle.ts"],"sourcesContent":["import type { Unsubscribe } from './service.js';\n\n/** A subscription that the caller can start and stop. Methods are bound. */\nexport interface Toggle {\n  /** Whether the subscription is running. */\n  readonly isActive: boolean;\n  /** Subscribe now, unless it is subscribed already. */\n  start: () => void;\n  /** Release the subscription, if it has one. */\n  stop: () => void;\n}\n\n/**\n * Make an unsubscribe-producing operation suspendable and resumable.\n *\n * `start()` and `stop()` are idempotent.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/toggle.html\n */\nexport function toggle(subscribe: () => Unsubscribe): Toggle {\n  let unsubscribe: Unsubscribe | null = null;\n  let isStarting = false;\n  let stopPending = false;\n\n  return {\n    get isActive() {\n      return unsubscribe !== null || (isStarting && !stopPending);\n    },\n    start: () => {\n      if (unsubscribe !== null || isStarting) {\n        return;\n      }\n\n      isStarting = true;\n      try {\n        const cleanup = subscribe();\n        if (stopPending) {\n          cleanup();\n        } else {\n          unsubscribe = cleanup;\n        }\n      } finally {\n        isStarting = false;\n        stopPending = false;\n      }\n    },\n    stop: () => {\n      if (isStarting) {\n        stopPending = true;\n        return;\n      }\n\n      const cleanup = unsubscribe;\n      unsubscribe = null;\n      cleanup?.();\n    },\n  };\n}\n"],"mappings":";;;;;;;AAkBA,SAAgB,OAAO,WAAsC;CAC3D,IAAI,cAAkC;CACtC,IAAI,aAAa;CACjB,IAAI,cAAc;CAElB,OAAO;EACL,IAAI,WAAW;GACb,OAAO,gBAAgB,QAAS,cAAc,CAAC;EACjD;EACA,aAAa;GACX,IAAI,gBAAgB,QAAQ,YAC1B;GAGF,aAAa;GACb,IAAI;IACF,MAAM,UAAU,UAAU;IAC1B,IAAI,aACF,QAAQ;SAER,cAAc;GAElB,UAAU;IACR,aAAa;IACb,cAAc;GAChB;EACF;EACA,YAAY;GACV,IAAI,YAAY;IACd,cAAc;IACd;GACF;GAEA,MAAM,UAAU;GAChB,cAAc;GACd,UAAU;EACZ;CACF;AACF"}

package/dist/services/until.d.ts

@@ -0,0 +1,11 @@
+import { Service } from "./service.js";
+//#region src/services/until.d.ts
+/**
+ * Wait for current or future service props that satisfy a predicate.
+ *
+ * The subscription is released before resolution. Object props are copied because services can reuse them.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/until.html
+ */
+declare function until<T>(service: Service<T>, predicate: (props: T) => boolean): Promise<T>;
+//#endregion
+export { until };