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

package/dist/responsive-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responsive-options.js","names":[],"sources":["../src/responsive-options.ts"],"sourcesContent":["/**\n * Responsive options cascade from the active breakpoint through narrower breakpoints to the unsuffixed base value.\n *\n * Values are resolved on read and are not stored.\n */\nimport { NEGATED_RAW, namespaceQualifier, namespacedAttribute } from './attributes.js';\nimport { warnOnce } from './diagnostics.js';\nimport { registerDOMOptionAttributes, replaceDOMOptionAttributes } from './dom-mutations.js';\nimport { breakpointNames, onBreakpointsReplaced, useBreakpoint } from './services/breakpoint.js';\nimport { getSharedRuntimeSlot } from './shared-runtime.js';\nimport { memo, type Memo } from './utils/memo.js';\n\n/** Memoized scoped attribute names for the current breakpoint set. */\ninterface ResponsiveOptionsRuntimeState {\n  scopedAttributes: Memo<[attribute: string], readonly string[]>;\n  observed: Set<string>;\n  isReplacementListenerAttached: boolean;\n}\n\nconst responsiveOptionsState = /* @__PURE__ */ getSharedRuntimeSlot<ResponsiveOptionsRuntimeState>(\n  'responsive-options',\n  2,\n  () => ({\n    scopedAttributes: memo((attribute: string): readonly string[] =>\n      breakpointNames().map((name) => namespacedAttribute(attribute, name)),\n    ),\n    observed: new Set(),\n    isReplacementListenerAttached: false,\n  }),\n);\nconst { scopedAttributes, observed } = responsiveOptionsState;\n\n/**\n * Exact scoped spellings used by declaration cascades and observer filters.\n * @internal\n */\nexport function responsiveAttributeNames(attribute: string): readonly string[] {\n  return scopedAttributes(attribute);\n}\n\n/** Base attributes whose scoped spellings the one observer filters for. */\nif (!responsiveOptionsState.isReplacementListenerAttached) {\n  responsiveOptionsState.isReplacementListenerAttached = true;\n  onBreakpointsReplaced(() => {\n    const previous = [...observed].flatMap((attribute) => scopedAttributes(attribute));\n    scopedAttributes.clear();\n    // Replace exact observer filter names when the breakpoint set changes.\n    const next = [...observed].flatMap((attribute) => scopedAttributes(attribute));\n    replaceDOMOptionAttributes(previous, next);\n  });\n}\n\n/** Add an attribute's breakpoint-scoped names to the mutation observer filter. */\nexport function observeResponsiveAttribute(attribute: string): void {\n  observed.add(attribute);\n  registerDOMOptionAttributes(scopedAttributes(attribute));\n}\n\n/** Return the widest matching breakpoint without creating a subscription. */\nexport function activeBreakpoint(): string {\n  return useBreakpoint().props().name;\n}\n\n/**\n * Resolve a raw option value by cascading from a breakpoint to the base attribute.\n *\n * `negated` is the off spelling of a boolean option, consulted at each level\n * **after** the on spelling: a narrower breakpoint wins over a wider one\n * whichever spelling it uses, and at one breakpoint the positive attribute\n * wins, since declaring both there says nothing coherent. It resolves to\n * `NEGATED_RAW`, so one cascade answers both spellings.\n */\nexport function responsiveRawValue(\n  attribute: string,\n  breakpoint: string,\n  get: (name: string) => string | null,\n  negated?: string,\n): string | null {\n  if (negated === undefined) {\n    return responsiveScopedRawValue(attribute, breakpoint, get) ?? get(attribute);\n  }\n\n  const names = breakpointNames();\n  const scoped = scopedAttributes(attribute);\n  const scopedNegations = scopedAttributes(negated);\n  for (let index = names.indexOf(breakpoint); index >= 0; index -= 1) {\n    const value = get(scoped[index]);\n    if (value !== null) {\n      return value;\n    }\n    if (get(scopedNegations[index]) !== null) {\n      return NEGATED_RAW;\n    }\n  }\n\n  return get(attribute) ?? (get(negated) === null ? null : NEGATED_RAW);\n}\n\n/**\n * The scoped value in force at one breakpoint, without falling back to the\n * plain attribute. An empty string is a present override; `null` means no\n * scoped candidate was present.\n *\n * @internal\n */\nexport function responsiveScopedRawValue(\n  attribute: string,\n  breakpoint: string,\n  get: (name: string) => string | null,\n): string | null {\n  const names = breakpointNames();\n  const scoped = scopedAttributes(attribute);\n  for (let index = names.indexOf(breakpoint); index >= 0; index -= 1) {\n    const value = get(scoped[index]);\n    if (value !== null) {\n      return value;\n    }\n  }\n  return null;\n}\n\n/** Watch breakpoint changes and pass the previous breakpoint to the callback. */\nexport function watchBreakpoint(callback: (previous: string) => void): () => void {\n  let previous = activeBreakpoint();\n  return useBreakpoint().subscribe(({ name }) => {\n    const left = previous;\n    previous = name;\n    callback(left);\n  });\n}\n\n/** Warn once for each responsive attribute suffix that names no breakpoint. */\nexport function checkResponsiveAttributes(el: HTMLElement, attributes: readonly string[]): void {\n  if (attributes.length === 0) {\n    return;\n  }\n  const names = breakpointNames();\n  for (const name of el.getAttributeNames()) {\n    for (const attribute of attributes) {\n      // The qualifier of a generated namespace is one breakpoint and nothing\n      // else, so an unknown one is a typo rather than a part core cannot read.\n      const qualifier = namespaceQualifier(attribute, name);\n      if (qualifier !== null && !names.includes(qualifier)) {\n        warnOnce(\n          el,\n          name,\n          'responsive.unknown-breakpoint',\n          `\\`${name}\\` names no breakpoint, so it is never read. One breakpoint per attribute, cascading upwards from it — known names: ${names.join(', ')}.`,\n          { target: el },\n        );\n        break;\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAmBA,MAAM,yBAAyC,qCAC7C,sBACA,UACO;CACL,kBAAkB,MAAM,cACtB,gBAAgB,CAAC,CAAC,KAAK,SAAS,oBAAoB,WAAW,IAAI,CAAC,CACtE;CACA,0BAAU,IAAI,IAAI;CAClB,+BAA+B;AACjC,EACF;AACA,MAAM,EAAE,kBAAkB,aAAa;;;;;AAMvC,SAAgB,yBAAyB,WAAsC;CAC7E,OAAO,iBAAiB,SAAS;AACnC;;AAGA,IAAI,CAAC,uBAAuB,+BAA+B;CACzD,uBAAuB,gCAAgC;CACvD,4BAA4B;EAC1B,MAAM,WAAW,CAAC,GAAG,QAAQ,CAAC,CAAC,SAAS,cAAc,iBAAiB,SAAS,CAAC;EACjF,iBAAiB,MAAM;EAEvB,MAAM,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,SAAS,cAAc,iBAAiB,SAAS,CAAC;EAC7E,2BAA2B,UAAU,IAAI;CAC3C,CAAC;AACH;;AAGA,SAAgB,2BAA2B,WAAyB;CAClE,SAAS,IAAI,SAAS;CACtB,4BAA4B,iBAAiB,SAAS,CAAC;AACzD;;AAGA,SAAgB,mBAA2B;CACzC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AACjC;;;;;;;;;;AAWA,SAAgB,mBACd,WACA,YACA,KACA,SACe;CACf,IAAI,YAAY,KAAA,GACd,OAAO,yBAAyB,WAAW,YAAY,GAAG,KAAK,IAAI,SAAS;CAG9E,MAAM,QAAQ,gBAAgB;CAC9B,MAAM,SAAS,iBAAiB,SAAS;CACzC,MAAM,kBAAkB,iBAAiB,OAAO;CAChD,KAAK,IAAI,QAAQ,MAAM,QAAQ,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG;EAClE,MAAM,QAAQ,IAAI,OAAO,MAAM;EAC/B,IAAI,UAAU,MACZ,OAAO;EAET,IAAI,IAAI,gBAAgB,MAAM,MAAM,MAClC,OAAA;CAEJ;CAEA,OAAO,IAAI,SAAS,MAAM,IAAI,OAAO,MAAM,OAAO,OAAA;AACpD;;;;;;;;AASA,SAAgB,yBACd,WACA,YACA,KACe;CACf,MAAM,QAAQ,gBAAgB;CAC9B,MAAM,SAAS,iBAAiB,SAAS;CACzC,KAAK,IAAI,QAAQ,MAAM,QAAQ,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG;EAClE,MAAM,QAAQ,IAAI,OAAO,MAAM;EAC/B,IAAI,UAAU,MACZ,OAAO;CAEX;CACA,OAAO;AACT;;AAGA,SAAgB,gBAAgB,UAAkD;CAChF,IAAI,WAAW,iBAAiB;CAChC,OAAO,cAAc,CAAC,CAAC,WAAW,EAAE,WAAW;EAC7C,MAAM,OAAO;EACb,WAAW;EACX,SAAS,IAAI;CACf,CAAC;AACH;;AAGA,SAAgB,0BAA0B,IAAiB,YAAqC;CAC9F,IAAI,WAAW,WAAW,GACxB;CAEF,MAAM,QAAQ,gBAAgB;CAC9B,KAAK,MAAM,QAAQ,GAAG,kBAAkB,GACtC,KAAK,MAAM,aAAa,YAAY;EAGlC,MAAM,YAAY,mBAAmB,WAAW,IAAI;EACpD,IAAI,cAAc,QAAQ,CAAC,MAAM,SAAS,SAAS,GAAG;GACpD,SACE,IACA,MACA,iCACA,KAAK,KAAK,sHAAsH,MAAM,KAAK,IAAI,EAAE,IACjJ,EAAE,QAAQ,GAAG,CACf;GACA;EACF;CACF;AAEJ"}

package/dist/scheduler.d.ts

@@ -0,0 +1,51 @@
+//#region src/scheduler.d.ts
+type SchedulerPhase = 'idle' | 'tick' | 'read' | 'write' | 'background';
+/** Frame timestamp and elapsed time clamped to `[1, 40]` ms. */
+interface TickProps {
+  readonly time: DOMHighResTimeStamp;
+  readonly delta: number;
+}
+type TickCallback = (props: TickProps) => void;
+/**
+ * Cancelable handle returned for every scheduled task. The promise resolves
+ * with the task's return value, or `undefined` when the task was canceled.
+ */
+interface ScheduledTask<T = unknown> {
+  promise: Promise<T | undefined>;
+  cancel(): void;
+}
+/**
+ * Frame-aligned scheduler with `tick → read → write` phases and an off-frame background lane.
+ *
+ * Tasks added to the active or completed phase wait for the next frame. Writes added during reads run in the same frame. Background work never requests a frame.
+ */
+declare class Scheduler {
+  #private;
+  get phase(): SchedulerPhase;
+  /**
+   * Subscribe before the read phase. Tick subscribers do not keep `whenIdle()` pending.
+   *
+   * @returns Unsubscribe.
+   */
+  tick(callback: TickCallback): () => void;
+  read<T>(fn: () => T): ScheduledTask<T>;
+  write<T>(fn: () => T): ScheduledTask<T>;
+  /** Schedule time-sliced low-priority work outside animation frames. */
+  background<T>(fn: () => T): ScheduledTask<T>;
+  /**
+   * Resolves once every queue is empty and no flush is scheduled.
+   */
+  whenIdle(): Promise<void>;
+}
+/**
+ * The one frame-aligned scheduler: the clock of the framework.
+ * @link https://js-toolkit-v4.studiometa.dev/api/scheduler/defaultScheduler.html
+ */
+declare const defaultScheduler: Scheduler;
+/**
+ * Await the next animation frame.
+ * @link https://js-toolkit-v4.studiometa.dev/api/scheduler/nextFrame.html
+ */
+declare function nextFrame(): Promise<void>;
+//#endregion
+export { ScheduledTask, Scheduler, SchedulerPhase, TickCallback, TickProps, defaultScheduler, nextFrame };

package/dist/scheduler.js

@@ -0,0 +1,217 @@
+import { getSharedRuntimeSlot } from "./shared-runtime.js";
+import { reportDiagnostic } from "./diagnostics.js";
+//#region src/scheduler.ts
+/** Background work budget per turn, measured from the drain start. */
+const BACKGROUND_BUDGET = 5;
+/** Clamp frame deltas to prevent jumps after long pauses. */
+const MIN_DELTA = 1;
+const MAX_DELTA = 40;
+/** The first tick uses one 60 Hz frame because no prior timestamp exists. */
+const DEFAULT_DELTA = 1e3 / 60;
+/** Queued frame phases in execution order. */
+const FRAME_PHASES = ["read", "write"];
+/** Pending background turns, and the port that runs them. */
+const turns = [];
+let channel;
+/** Post background work through `scheduler.postTask`, with a `MessageChannel` fallback. */
+function postMessageTask(run) {
+	if (!channel) {
+		channel = new MessageChannel();
+		channel.port1.onmessage = () => turns.shift()?.();
+	}
+	turns.push(run);
+	channel.port2.postMessage(null);
+}
+function postBackgroundTask(run) {
+	const nativeScheduler = globalThis.scheduler;
+	if (typeof nativeScheduler?.postTask === "function") {
+		nativeScheduler.postTask(run, { priority: "background" }).catch((error) => {
+			reportDiagnostic("scheduler.background-post-failed", "The native scheduler rejected a background post.", error);
+			postMessageTask(run);
+		});
+		return;
+	}
+	postMessageTask(run);
+}
+/**
+* Frame-aligned scheduler with `tick → read → write` phases and an off-frame background lane.
+*
+* Tasks added to the active or completed phase wait for the next frame. Writes added during reads run in the same frame. Background work never requests a frame.
+*/
+var Scheduler = class {
+	#queues = {
+		read: [],
+		write: [],
+		background: []
+	};
+	#phase = "idle";
+	#isScheduled = false;
+	#isBackgroundScheduled = false;
+	#idleResolvers = [];
+	#tickCallbacks = /* @__PURE__ */ new Set();
+	/**
+	* `-1` while nothing is subscribed, so the first tick after the loop wakes
+	* reports `DEFAULT_DELTA` instead of a measurement it cannot make.
+	*/
+	#lastFrameTime = -1;
+	get phase() {
+		return this.#phase;
+	}
+	/**
+	* Subscribe before the read phase. Tick subscribers do not keep `whenIdle()` pending.
+	*
+	* @returns Unsubscribe.
+	*/
+	tick(callback) {
+		if (this.#tickCallbacks.size === 0) this.#lastFrameTime = -1;
+		this.#tickCallbacks.add(callback);
+		this.#schedule();
+		return () => {
+			this.#tickCallbacks.delete(callback);
+		};
+	}
+	read(fn) {
+		return this.#add("read", fn);
+	}
+	write(fn) {
+		return this.#add("write", fn);
+	}
+	/** Schedule time-sliced low-priority work outside animation frames. */
+	background(fn) {
+		return this.#add("background", fn);
+	}
+	/**
+	* Resolves once every queue is empty and no flush is scheduled.
+	*/
+	whenIdle() {
+		if (this.#isIdle()) return Promise.resolve();
+		return new Promise((resolve) => this.#idleResolvers.push(resolve));
+	}
+	/**
+	* Idleness is about queued tasks only: a tick subscription keeps the loop
+	* running forever by design, and a live service must not make
+	* `whenIdle()` wait for a queue that will never be the reason it resolves.
+	*/
+	#isIdle() {
+		return Object.values(this.#queues).every((queue) => queue.length === 0);
+	}
+	#add(queueName, fn) {
+		let resolve;
+		let reject;
+		const promise = new Promise((res, rej) => {
+			resolve = res;
+			reject = rej;
+		});
+		promise.catch(() => {});
+		const item = {
+			fn,
+			isCanceled: false,
+			resolve,
+			reject
+		};
+		this.#queues[queueName].push(item);
+		if (queueName === "background") this.#scheduleBackground();
+		else this.#schedule();
+		return {
+			promise,
+			cancel() {
+				item.isCanceled = true;
+			}
+		};
+	}
+	#schedule() {
+		if (this.#isScheduled) return;
+		this.#isScheduled = true;
+		requestAnimationFrame((frameTime) => this.#flush(frameTime));
+	}
+	#scheduleBackground() {
+		if (this.#isBackgroundScheduled) return;
+		this.#isBackgroundScheduled = true;
+		postBackgroundTask(() => this.#drainBackground());
+	}
+	/**
+	* One background turn: run tasks until the time slice runs out, then hand
+	* the thread back and post the next turn. The slice is measured from the
+	* start of the drain, so a busy frame cannot spend the lane's budget.
+	*/
+	#drainBackground() {
+		this.#isBackgroundScheduled = false;
+		const start = performance.now();
+		const queue = this.#queues.background;
+		this.#phase = "background";
+		while (queue.length > 0 && performance.now() - start < BACKGROUND_BUDGET) this.#run(queue.shift());
+		this.#phase = "idle";
+		if (queue.length > 0) this.#scheduleBackground();
+		this.#resolveIdle();
+	}
+	#flush(frameTime) {
+		this.#isScheduled = false;
+		if (this.#tickCallbacks.size > 0) {
+			this.#phase = "tick";
+			const props = {
+				time: frameTime,
+				delta: this.#clampDelta(frameTime)
+			};
+			this.#lastFrameTime = frameTime;
+			const callbacks = [...this.#tickCallbacks];
+			for (const callback of callbacks) {
+				if (!this.#tickCallbacks.has(callback)) continue;
+				try {
+					callback(props);
+				} catch (error) {
+					reportDiagnostic("callback.scheduler-tick-failed", "A scheduler tick callback failed.", error);
+				}
+			}
+		}
+		for (const phase of FRAME_PHASES) {
+			this.#phase = phase;
+			const batch = this.#queues[phase];
+			this.#queues[phase] = [];
+			for (const item of batch) this.#run(item);
+		}
+		this.#phase = "idle";
+		if (this.#hasFrameWork() || this.#tickCallbacks.size > 0) this.#schedule();
+		this.#resolveIdle();
+	}
+	#hasFrameWork() {
+		return FRAME_PHASES.some((phase) => this.#queues[phase].length > 0);
+	}
+	#clampDelta(frameTime) {
+		if (this.#lastFrameTime < 0) return DEFAULT_DELTA;
+		return Math.min(Math.max(frameTime - this.#lastFrameTime, MIN_DELTA), MAX_DELTA);
+	}
+	#resolveIdle() {
+		if (this.#idleResolvers.length === 0 || !this.#isIdle()) return;
+		const resolvers = this.#idleResolvers;
+		this.#idleResolvers = [];
+		for (const resolve of resolvers) resolve();
+	}
+	#run(item) {
+		if (item.isCanceled) {
+			item.resolve(void 0);
+			return;
+		}
+		try {
+			item.resolve(item.fn());
+		} catch (error) {
+			reportDiagnostic("callback.scheduled-task-failed", "A scheduled task failed.", error);
+			item.reject(error);
+		}
+	}
+};
+/**
+* The one frame-aligned scheduler: the clock of the framework.
+* @link https://js-toolkit-v4.studiometa.dev/api/scheduler/defaultScheduler.html
+*/
+const defaultScheduler = /* @__PURE__ */ getSharedRuntimeSlot("scheduler:default", 1, () => new Scheduler());
+/**
+* Await the next animation frame.
+* @link https://js-toolkit-v4.studiometa.dev/api/scheduler/nextFrame.html
+*/
+function nextFrame() {
+	return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+}
+//#endregion
+export { Scheduler, defaultScheduler, nextFrame };
+
+//# sourceMappingURL=scheduler.js.map

package/dist/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","names":["#phase","#tickCallbacks","#lastFrameTime","#schedule","#add","#isIdle","#idleResolvers","#queues","#scheduleBackground","#isScheduled","#flush","#isBackgroundScheduled","#drainBackground","#run","#resolveIdle","#clampDelta","#hasFrameWork"],"sources":["../src/scheduler.ts"],"sourcesContent":["import { reportDiagnostic } from './diagnostics.js';\nimport { getSharedRuntimeSlot } from './shared-runtime.js';\n\n/** Background work budget per turn, measured from the drain start. */\nconst BACKGROUND_BUDGET = 5;\n\n/** Clamp frame deltas to prevent jumps after long pauses. */\nconst MIN_DELTA = 1;\nconst MAX_DELTA = 40;\n\n/** The first tick uses one 60 Hz frame because no prior timestamp exists. */\nconst DEFAULT_DELTA = 1000 / 60;\n\nexport type SchedulerPhase = 'idle' | 'tick' | 'read' | 'write' | 'background';\n\ntype QueueName = 'read' | 'write' | 'background';\n\n/** Queued frame phases in execution order. */\nconst FRAME_PHASES = ['read', 'write'] as const;\n\n/** Frame timestamp and elapsed time clamped to `[1, 40]` ms. */\nexport interface TickProps {\n  readonly time: DOMHighResTimeStamp;\n  readonly delta: number;\n}\n\nexport type TickCallback = (props: TickProps) => void;\n\n/** Pending background turns, and the port that runs them. */\nconst turns: Array<() => void> = [];\nlet channel: MessageChannel | undefined;\n\n/** Post background work through `scheduler.postTask`, with a `MessageChannel` fallback. */\nfunction postMessageTask(run: () => void): void {\n  // Open the channel lazily so importing the module does not open a port.\n  if (!channel) {\n    channel = new MessageChannel();\n    channel.port1.onmessage = () => turns.shift()?.();\n  }\n  turns.push(run);\n  channel.port2.postMessage(null);\n}\n\nfunction postBackgroundTask(run: () => void): void {\n  // Use the platform scheduler, not this module's scheduler.\n  const nativeScheduler = globalThis.scheduler;\n  if (typeof nativeScheduler?.postTask === 'function') {\n    nativeScheduler.postTask(run, { priority: 'background' }).catch((error: unknown) => {\n      reportDiagnostic(\n        'scheduler.background-post-failed',\n        'The native scheduler rejected a background post.',\n        error,\n      );\n      postMessageTask(run);\n    });\n    return;\n  }\n\n  postMessageTask(run);\n}\n\n/**\n * Cancelable handle returned for every scheduled task. The promise resolves\n * with the task's return value, or `undefined` when the task was canceled.\n */\nexport interface ScheduledTask<T = unknown> {\n  promise: Promise<T | undefined>;\n  cancel(): void;\n}\n\ninterface QueueItem {\n  fn: () => unknown;\n  isCanceled: boolean;\n  resolve: (value: unknown) => void;\n  reject: (reason: unknown) => void;\n}\n\n/**\n * Frame-aligned scheduler with `tick → read → write` phases and an off-frame background lane.\n *\n * Tasks added to the active or completed phase wait for the next frame. Writes added during reads run in the same frame. Background work never requests a frame.\n */\nexport class Scheduler {\n  #queues: Record<QueueName, QueueItem[]> = {\n    read: [],\n    write: [],\n    background: [],\n  };\n\n  #phase: SchedulerPhase = 'idle';\n\n  #isScheduled = false;\n\n  #isBackgroundScheduled = false;\n\n  #idleResolvers: Array<() => void> = [];\n\n  #tickCallbacks = new Set<TickCallback>();\n\n  /**\n   * `-1` while nothing is subscribed, so the first tick after the loop wakes\n   * reports `DEFAULT_DELTA` instead of a measurement it cannot make.\n   */\n  #lastFrameTime = -1;\n\n  get phase(): SchedulerPhase {\n    return this.#phase;\n  }\n\n  /**\n   * Subscribe before the read phase. Tick subscribers do not keep `whenIdle()` pending.\n   *\n   * @returns Unsubscribe.\n   */\n  tick(callback: TickCallback): () => void {\n    if (this.#tickCallbacks.size === 0) {\n      this.#lastFrameTime = -1;\n    }\n    this.#tickCallbacks.add(callback);\n    this.#schedule();\n    return () => {\n      this.#tickCallbacks.delete(callback);\n    };\n  }\n\n  read<T>(fn: () => T): ScheduledTask<T> {\n    return this.#add('read', fn);\n  }\n\n  write<T>(fn: () => T): ScheduledTask<T> {\n    return this.#add('write', fn);\n  }\n\n  /** Schedule time-sliced low-priority work outside animation frames. */\n  background<T>(fn: () => T): ScheduledTask<T> {\n    return this.#add('background', fn);\n  }\n\n  /**\n   * Resolves once every queue is empty and no flush is scheduled.\n   */\n  whenIdle(): Promise<void> {\n    if (this.#isIdle()) {\n      return Promise.resolve();\n    }\n    return new Promise((resolve) => this.#idleResolvers.push(resolve));\n  }\n\n  /**\n   * Idleness is about queued tasks only: a tick subscription keeps the loop\n   * running forever by design, and a live service must not make\n   * `whenIdle()` wait for a queue that will never be the reason it resolves.\n   */\n  #isIdle(): boolean {\n    return Object.values(this.#queues).every((queue) => queue.length === 0);\n  }\n\n  #add<T>(queueName: QueueName, fn: () => T): ScheduledTask<T> {\n    let resolve!: (value: unknown) => void;\n    let reject!: (reason: unknown) => void;\n    const promise = new Promise((res, rej) => {\n      resolve = res;\n      reject = rej;\n    });\n    // Mark the rejection as handled so callers that do not await never\n    // trigger an unhandled rejection; awaiting callers still get the error.\n    promise.catch(() => {});\n    const item: QueueItem = { fn, isCanceled: false, resolve, reject };\n    this.#queues[queueName].push(item);\n    if (queueName === 'background') {\n      this.#scheduleBackground();\n    } else {\n      this.#schedule();\n    }\n    return {\n      promise: promise as Promise<T | undefined>,\n      cancel() {\n        item.isCanceled = true;\n      },\n    };\n  }\n\n  #schedule(): void {\n    if (this.#isScheduled) {\n      return;\n    }\n    this.#isScheduled = true;\n    // Preserve the rAF timestamp for all callbacks in this frame.\n    requestAnimationFrame((frameTime) => this.#flush(frameTime));\n  }\n\n  #scheduleBackground(): void {\n    if (this.#isBackgroundScheduled) {\n      return;\n    }\n    this.#isBackgroundScheduled = true;\n    postBackgroundTask(() => this.#drainBackground());\n  }\n\n  /**\n   * One background turn: run tasks until the time slice runs out, then hand\n   * the thread back and post the next turn. The slice is measured from the\n   * start of the drain, so a busy frame cannot spend the lane's budget.\n   */\n  #drainBackground(): void {\n    this.#isBackgroundScheduled = false;\n    const start = performance.now();\n    const queue = this.#queues.background;\n\n    this.#phase = 'background';\n    while (queue.length > 0 && performance.now() - start < BACKGROUND_BUDGET) {\n      this.#run(queue.shift() as QueueItem);\n    }\n    this.#phase = 'idle';\n\n    if (queue.length > 0) {\n      this.#scheduleBackground();\n    }\n    this.#resolveIdle();\n  }\n\n  #flush(frameTime: DOMHighResTimeStamp): void {\n    this.#isScheduled = false;\n\n    if (this.#tickCallbacks.size > 0) {\n      this.#phase = 'tick';\n      const props: TickProps = {\n        time: frameTime,\n        delta: this.#clampDelta(frameTime),\n      };\n      this.#lastFrameTime = frameTime;\n      const callbacks = [...this.#tickCallbacks];\n      for (const callback of callbacks) {\n        // A subscription starts on the next frame. An unsubscribe takes\n        // effect at once, including before the callback's turn in this tick.\n        if (!this.#tickCallbacks.has(callback)) {\n          continue;\n        }\n        try {\n          callback(props);\n        } catch (error) {\n          // Reported and skipped, never unsubscribed: a subscription is\n          // owned by whoever created it, not by the frame that broke.\n          reportDiagnostic(\n            'callback.scheduler-tick-failed',\n            'A scheduler tick callback failed.',\n            error,\n          );\n        }\n      }\n    }\n\n    // Swap each phase queue before execution to prevent same-phase reentry.\n    for (const phase of FRAME_PHASES) {\n      this.#phase = phase;\n      const batch = this.#queues[phase];\n      this.#queues[phase] = [];\n      for (const item of batch) {\n        this.#run(item);\n      }\n    }\n\n    this.#phase = 'idle';\n\n    // The rAF loop exists for rendering work only. A pending background\n    // task must not hold a frame open — it drains on its own turns.\n    if (this.#hasFrameWork() || this.#tickCallbacks.size > 0) {\n      this.#schedule();\n    }\n    this.#resolveIdle();\n  }\n\n  #hasFrameWork(): boolean {\n    return FRAME_PHASES.some((phase) => this.#queues[phase].length > 0);\n  }\n\n  #clampDelta(frameTime: DOMHighResTimeStamp): number {\n    if (this.#lastFrameTime < 0) {\n      return DEFAULT_DELTA;\n    }\n    return Math.min(Math.max(frameTime - this.#lastFrameTime, MIN_DELTA), MAX_DELTA);\n  }\n\n  #resolveIdle(): void {\n    if (this.#idleResolvers.length === 0 || !this.#isIdle()) {\n      return;\n    }\n    const resolvers = this.#idleResolvers;\n    this.#idleResolvers = [];\n    for (const resolve of resolvers) {\n      resolve();\n    }\n  }\n\n  #run(item: QueueItem): void {\n    if (item.isCanceled) {\n      item.resolve(undefined);\n      return;\n    }\n    try {\n      item.resolve(item.fn());\n    } catch (error) {\n      // The task's promise keeps the original rejection for its owner. The\n      // diagnostic reports the recovered scheduler failure independently.\n      reportDiagnostic('callback.scheduled-task-failed', 'A scheduled task failed.', error);\n      item.reject(error);\n    }\n  }\n}\n\n/**\n * The one frame-aligned scheduler: the clock of the framework.\n * @link https://js-toolkit-v4.studiometa.dev/api/scheduler/defaultScheduler.html\n */\nexport const defaultScheduler = /* @__PURE__ */ getSharedRuntimeSlot(\n  'scheduler:default',\n  1,\n  () => new Scheduler(),\n);\n\n/**\n * Await the next animation frame.\n * @link https://js-toolkit-v4.studiometa.dev/api/scheduler/nextFrame.html\n */\nexport function nextFrame(): Promise<void> {\n  return new Promise((resolve) => requestAnimationFrame(() => resolve()));\n}\n"],"mappings":"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"}

package/dist/services/breakpoint.d.ts

@@ -0,0 +1,35 @@
+import { Service } from "./service.js";
+//#region src/services/breakpoint.d.ts
+/**
+ * Default named viewport widths, ascending. Media-query `rem` uses the browser's initial font size, not the root element's computed size.
+ * @link https://js-toolkit-v4.studiometa.dev/api/dom/breakpoints.html
+ */
+declare const BREAKPOINTS: Readonly<Record<string, string>>;
+interface BreakpointProps {
+  /**
+   * Name of the widest breakpoint the viewport currently matches, `''` when
+   * the set has no breakpoint the viewport reaches.
+   */
+  readonly name: string;
+}
+/**
+ * Replace the ascending named breakpoint set and refresh active subscribers.
+ * @link https://js-toolkit-v4.studiometa.dev/api/dom/breakpoints.html
+ */
+declare function setBreakpoints(next: Record<string, string>): void;
+/**
+ * Return a copy of the active breakpoint set.
+ * @link https://js-toolkit-v4.studiometa.dev/api/dom/breakpoints.html
+ */
+declare function getBreakpoints(): Record<string, string>;
+/** Return breakpoint names from narrowest to widest without copying. @internal */
+declare function breakpointNames(): readonly string[];
+/** Subscribe to breakpoint-set replacement, not viewport crossings. @internal */
+declare function onBreakpointsReplaced(callback: () => void): () => void;
+/**
+ * Use the viewport breakpoint service. It listens to media-query crossings, including changes caused by the browser's initial font size.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/useBreakpoint.html
+ */
+declare function useBreakpoint(): Service<BreakpointProps>;
+//#endregion
+export { BREAKPOINTS, BreakpointProps, breakpointNames, getBreakpoints, onBreakpointsReplaced, setBreakpoints, useBreakpoint };

package/dist/services/breakpoint.js

@@ -0,0 +1,130 @@
+import { memo } from "../utils/memo.js";
+import { getSharedRuntimeSlot } from "../shared-runtime.js";
+import { createService } from "./service.js";
+//#region src/services/breakpoint.ts
+/**
+* Default named viewport widths, ascending. Media-query `rem` uses the browser's initial font size, not the root element's computed size.
+* @link https://js-toolkit-v4.studiometa.dev/api/dom/breakpoints.html
+*/
+const BREAKPOINTS = {
+	xxs: "0rem",
+	xs: "30rem",
+	s: "48rem",
+	m: "64rem",
+	l: "80rem",
+	xl: "90rem",
+	xxl: "120rem",
+	xxxl: "160rem"
+};
+const breakpointState = /* @__PURE__ */ getSharedRuntimeSlot("service:breakpoint", 1, () => ({
+	breakpoints: { ...BREAKPOINTS },
+	queries: null,
+	refresh: null,
+	names: null,
+	replacementListeners: /* @__PURE__ */ new Set(),
+	widestMatch: memo(() => {
+		let match = "";
+		for (const [name, query] of queryList()) if (query.matches) match = name;
+		return match;
+	}),
+	invalidating: false,
+	service: void 0
+}));
+const { replacementListeners, widestMatch } = breakpointState;
+/** Build media-query lists lazily and keep them until the set changes. */
+function queryList() {
+	breakpointState.queries ??= Object.entries(breakpointState.breakpoints).map(([name, value]) => [name, window.matchMedia(`(min-width: ${value})`)]);
+	return breakpointState.queries;
+}
+/**
+* Replace the ascending named breakpoint set and refresh active subscribers.
+* @link https://js-toolkit-v4.studiometa.dev/api/dom/breakpoints.html
+*/
+function setBreakpoints(next) {
+	breakpointState.breakpoints = { ...next };
+	breakpointState.queries = null;
+	breakpointState.names = null;
+	widestMatch.clear();
+	for (const listener of replacementListeners) listener();
+	breakpointState.refresh?.();
+}
+/**
+* Return a copy of the active breakpoint set.
+* @link https://js-toolkit-v4.studiometa.dev/api/dom/breakpoints.html
+*/
+function getBreakpoints() {
+	return { ...breakpointState.breakpoints };
+}
+/** Return breakpoint names from narrowest to widest without copying. @internal */
+function breakpointNames() {
+	breakpointState.names ??= Object.keys(breakpointState.breakpoints);
+	return breakpointState.names;
+}
+/** Subscribe to breakpoint-set replacement, not viewport crossings. @internal */
+function onBreakpointsReplaced(callback) {
+	replacementListeners.add(callback);
+	return () => {
+		replacementListeners.delete(callback);
+	};
+}
+/**
+* Return the widest matching breakpoint, cached for the current task. Set replacement and media-query changes invalidate it immediately.
+*/
+function currentBreakpoint() {
+	if (!breakpointState.invalidating) {
+		breakpointState.invalidating = true;
+		queueMicrotask(() => {
+			breakpointState.invalidating = false;
+			widestMatch.clear();
+		});
+	}
+	return widestMatch();
+}
+function createBreakpointService() {
+	const props = { name: "" };
+	return createService({
+		props: () => {
+			props.name = currentBreakpoint();
+			return props;
+		},
+		start(emit) {
+			const publishIfCrossed = () => {
+				widestMatch.clear();
+				const name = currentBreakpoint();
+				if (name === props.name) return;
+				props.name = name;
+				emit(props);
+			};
+			const listen = () => {
+				const listening = queryList();
+				for (const [, query] of listening) query.addEventListener("change", publishIfCrossed);
+				return () => {
+					for (const [, query] of listening) query.removeEventListener("change", publishIfCrossed);
+				};
+			};
+			props.name = currentBreakpoint();
+			let unlisten = listen();
+			breakpointState.refresh = () => {
+				unlisten();
+				unlisten = listen();
+				publishIfCrossed();
+			};
+			return () => {
+				unlisten();
+				breakpointState.refresh = null;
+			};
+		}
+	});
+}
+/**
+* Use the viewport breakpoint service. It listens to media-query crossings, including changes caused by the browser's initial font size.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/useBreakpoint.html
+*/
+function useBreakpoint() {
+	breakpointState.service ??= createBreakpointService();
+	return breakpointState.service;
+}
+//#endregion
+export { BREAKPOINTS, breakpointNames, getBreakpoints, onBreakpointsReplaced, setBreakpoints, useBreakpoint };
+
+//# sourceMappingURL=breakpoint.js.map

package/dist/services/breakpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakpoint.js","names":[],"sources":["../../src/services/breakpoint.ts"],"sourcesContent":["import { getSharedRuntimeSlot } from '../shared-runtime.js';\nimport { memo, type Memo } from '../utils/memo.js';\nimport { createService, type MutableProps, type Service } from './service.js';\n\n/**\n * Default named viewport widths, ascending. Media-query `rem` uses the browser's initial font size, not the root element's computed size.\n * @link https://js-toolkit-v4.studiometa.dev/api/dom/breakpoints.html\n */\nexport const BREAKPOINTS: Readonly<Record<string, string>> = {\n  xxs: '0rem',\n  xs: '30rem',\n  s: '48rem',\n  m: '64rem',\n  l: '80rem',\n  xl: '90rem',\n  xxl: '120rem',\n  xxxl: '160rem',\n};\n\nexport interface BreakpointProps {\n  /**\n   * Name of the widest breakpoint the viewport currently matches, `''` when\n   * the set has no breakpoint the viewport reaches.\n   */\n  readonly name: string;\n}\n\ninterface BreakpointRuntimeState {\n  breakpoints: Record<string, string>;\n  queries: Array<readonly [string, MediaQueryList]> | null;\n  refresh: (() => void) | null;\n  names: readonly string[] | null;\n  replacementListeners: Set<() => void>;\n  widestMatch: Memo<[], string>;\n  invalidating: boolean;\n  service: Service<BreakpointProps> | undefined;\n}\n\nconst breakpointState = /* @__PURE__ */ getSharedRuntimeSlot<BreakpointRuntimeState>(\n  'service:breakpoint',\n  1,\n  () => ({\n    breakpoints: { ...BREAKPOINTS },\n    queries: null,\n    refresh: null,\n    names: null,\n    replacementListeners: new Set(),\n    widestMatch: memo((): string => {\n      let match = '';\n      for (const [name, query] of queryList()) {\n        if (query.matches) {\n          match = name;\n        }\n      }\n      return match;\n    }),\n    invalidating: false,\n    service: undefined,\n  }),\n);\nconst { replacementListeners, widestMatch } = breakpointState;\n\n/** Build media-query lists lazily and keep them until the set changes. */\nfunction queryList(): Array<readonly [string, MediaQueryList]> {\n  breakpointState.queries ??= Object.entries(breakpointState.breakpoints).map(\n    ([name, value]) => [name, window.matchMedia(`(min-width: ${value})`)] as const,\n  );\n  return breakpointState.queries;\n}\n\n/**\n * Replace the ascending named breakpoint set and refresh active subscribers.\n * @link https://js-toolkit-v4.studiometa.dev/api/dom/breakpoints.html\n */\nexport function setBreakpoints(next: Record<string, string>): void {\n  breakpointState.breakpoints = { ...next };\n  breakpointState.queries = null;\n  breakpointState.names = null;\n  // A set replacement has no `matchMedia` event, so invalidate synchronously.\n  widestMatch.clear();\n  // Invalidate derived caches before notifying subscribers.\n  for (const listener of replacementListeners) {\n    listener();\n  }\n  breakpointState.refresh?.();\n}\n\n/**\n * Return a copy of the active breakpoint set.\n * @link https://js-toolkit-v4.studiometa.dev/api/dom/breakpoints.html\n */\nexport function getBreakpoints(): Record<string, string> {\n  return { ...breakpointState.breakpoints };\n}\n\n/** Return breakpoint names from narrowest to widest without copying. @internal */\nexport function breakpointNames(): readonly string[] {\n  breakpointState.names ??= Object.keys(breakpointState.breakpoints);\n  return breakpointState.names;\n}\n\n/** Subscribe to breakpoint-set replacement, not viewport crossings. @internal */\nexport function onBreakpointsReplaced(callback: () => void): () => void {\n  replacementListeners.add(callback);\n  return () => {\n    replacementListeners.delete(callback);\n  };\n}\n\n/**\n * Return the widest matching breakpoint, cached for the current task. Set replacement and media-query changes invalidate it immediately.\n */\nfunction currentBreakpoint(): string {\n  if (!breakpointState.invalidating) {\n    breakpointState.invalidating = true;\n    queueMicrotask(() => {\n      breakpointState.invalidating = false;\n      widestMatch.clear();\n    });\n  }\n  return widestMatch();\n}\n\nfunction createBreakpointService(): Service<BreakpointProps> {\n  const props: MutableProps<BreakpointProps> = { name: '' };\n\n  return createService<BreakpointProps>({\n    // Media queries provide a current value without a subscription.\n    props: () => {\n      props.name = currentBreakpoint();\n      return props;\n    },\n    start(emit) {\n      const publishIfCrossed = () => {\n        // A media-query change invalidates the task cache immediately.\n        widestMatch.clear();\n        const name = currentBreakpoint();\n        if (name === props.name) {\n          return;\n        }\n        props.name = name;\n        emit(props);\n      };\n\n      const listen = () => {\n        const listening = queryList();\n        for (const [, query] of listening) {\n          query.addEventListener('change', publishIfCrossed);\n        }\n        return () => {\n          for (const [, query] of listening) {\n            query.removeEventListener('change', publishIfCrossed);\n          }\n        };\n      };\n\n      props.name = currentBreakpoint();\n      let unlisten = listen();\n      breakpointState.refresh = () => {\n        unlisten();\n        unlisten = listen();\n        publishIfCrossed();\n      };\n\n      return () => {\n        unlisten();\n        breakpointState.refresh = null;\n      };\n    },\n  });\n}\n\n/**\n * Use the viewport breakpoint service. It listens to media-query crossings, including changes caused by the browser's initial font size.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/useBreakpoint.html\n */\nexport function useBreakpoint(): Service<BreakpointProps> {\n  breakpointState.service ??= createBreakpointService();\n  return breakpointState.service;\n}\n"],"mappings":";;;;;;;;AAQA,MAAa,cAAgD;CAC3D,KAAK;CACL,IAAI;CACJ,GAAG;CACH,GAAG;CACH,GAAG;CACH,IAAI;CACJ,KAAK;CACL,MAAM;AACR;AAqBA,MAAM,kBAAkC,qCACtC,sBACA,UACO;CACL,aAAa,EAAE,GAAG,YAAY;CAC9B,SAAS;CACT,SAAS;CACT,OAAO;CACP,sCAAsB,IAAI,IAAI;CAC9B,aAAa,WAAmB;EAC9B,IAAI,QAAQ;EACZ,KAAK,MAAM,CAAC,MAAM,UAAU,UAAU,GACpC,IAAI,MAAM,SACR,QAAQ;EAGZ,OAAO;CACT,CAAC;CACD,cAAc;CACd,SAAS,KAAA;AACX,EACF;AACA,MAAM,EAAE,sBAAsB,gBAAgB;;AAG9C,SAAS,YAAsD;CAC7D,gBAAgB,YAAY,OAAO,QAAQ,gBAAgB,WAAW,CAAC,CAAC,KACrE,CAAC,MAAM,WAAW,CAAC,MAAM,OAAO,WAAW,eAAe,MAAM,EAAE,CAAC,CACtE;CACA,OAAO,gBAAgB;AACzB;;;;;AAMA,SAAgB,eAAe,MAAoC;CACjE,gBAAgB,cAAc,EAAE,GAAG,KAAK;CACxC,gBAAgB,UAAU;CAC1B,gBAAgB,QAAQ;CAExB,YAAY,MAAM;CAElB,KAAK,MAAM,YAAY,sBACrB,SAAS;CAEX,gBAAgB,UAAU;AAC5B;;;;;AAMA,SAAgB,iBAAyC;CACvD,OAAO,EAAE,GAAG,gBAAgB,YAAY;AAC1C;;AAGA,SAAgB,kBAAqC;CACnD,gBAAgB,UAAU,OAAO,KAAK,gBAAgB,WAAW;CACjE,OAAO,gBAAgB;AACzB;;AAGA,SAAgB,sBAAsB,UAAkC;CACtE,qBAAqB,IAAI,QAAQ;CACjC,aAAa;EACX,qBAAqB,OAAO,QAAQ;CACtC;AACF;;;;AAKA,SAAS,oBAA4B;CACnC,IAAI,CAAC,gBAAgB,cAAc;EACjC,gBAAgB,eAAe;EAC/B,qBAAqB;GACnB,gBAAgB,eAAe;GAC/B,YAAY,MAAM;EACpB,CAAC;CACH;CACA,OAAO,YAAY;AACrB;AAEA,SAAS,0BAAoD;CAC3D,MAAM,QAAuC,EAAE,MAAM,GAAG;CAExD,OAAO,cAA+B;EAEpC,aAAa;GACX,MAAM,OAAO,kBAAkB;GAC/B,OAAO;EACT;EACA,MAAM,MAAM;GACV,MAAM,yBAAyB;IAE7B,YAAY,MAAM;IAClB,MAAM,OAAO,kBAAkB;IAC/B,IAAI,SAAS,MAAM,MACjB;IAEF,MAAM,OAAO;IACb,KAAK,KAAK;GACZ;GAEA,MAAM,eAAe;IACnB,MAAM,YAAY,UAAU;IAC5B,KAAK,MAAM,GAAG,UAAU,WACtB,MAAM,iBAAiB,UAAU,gBAAgB;IAEnD,aAAa;KACX,KAAK,MAAM,GAAG,UAAU,WACtB,MAAM,oBAAoB,UAAU,gBAAgB;IAExD;GACF;GAEA,MAAM,OAAO,kBAAkB;GAC/B,IAAI,WAAW,OAAO;GACtB,gBAAgB,gBAAgB;IAC9B,SAAS;IACT,WAAW,OAAO;IAClB,iBAAiB;GACnB;GAEA,aAAa;IACX,SAAS;IACT,gBAAgB,UAAU;GAC5B;EACF;CACF,CAAC;AACH;;;;;AAMA,SAAgB,gBAA0C;CACxD,gBAAgB,YAAY,wBAAwB;CACpD,OAAO,gBAAgB;AACzB"}

package/dist/services/drag.d.ts

@@ -0,0 +1,65 @@
+import { Service } from "./service.js";
+import { ServiceHandles, ServiceMixin, ServiceMixinOptions } from "./mixin.js";
+//#region src/services/drag.d.ts
+/** Anything that can be grabbed: an HTML element, or an SVG one. */
+type DragTarget = HTMLElement | SVGElement;
+/**
+ * Drag lifecycle modes: `idle → start → drag → drop → inertia → stop → idle`.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/useDrag.html
+ */
+declare const DRAG_MODES: {
+  readonly IDLE: 'idle';
+  readonly START: 'start';
+  readonly DRAG: 'drag';
+  readonly DROP: 'drop';
+  readonly INERTIA: 'inertia';
+  readonly STOP: 'stop';
+};
+/** One of {@link DRAG_MODES}. */
+type DragMode = (typeof DRAG_MODES)[keyof typeof DRAG_MODES];
+/** Drag state for both viewport axes. */
+interface DragProps {
+  readonly mode: DragMode;
+  /** Current position in the viewport. */
+  readonly x: number;
+  readonly y: number;
+  /** Movement since the previous update. */
+  readonly deltaX: number;
+  readonly deltaY: number;
+  /** Where the drag started. */
+  readonly originX: number;
+  readonly originY: number;
+  /** Distance from the origin to the current position. */
+  readonly distanceX: number;
+  readonly distanceY: number;
+  /** Position the inertia is heading to. */
+  readonly finalX: number;
+  readonly finalY: number;
+}
+interface DragOptions {
+  /** Which movement the drag owns. Defaults to `both`. */
+  axis?: 'x' | 'y' | 'both';
+  /** How fast the inertia decays, from `0` (none) to `1` (endless). */
+  dampFactor?: number;
+  /** Movement past which a drag stops counting as a click, in pixels. */
+  dragThreshold?: number;
+  /** Whether to coast after `drop`. Defaults to `true`. */
+  inertia?: boolean;
+}
+/**
+ * Use one shared drag service per target and option set.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/useDrag.html
+ */
+declare function useDrag(target: DragTarget, options?: DragOptions): Service<DragProps>;
+/** The method `withDrag()` subscribes for the component. */
+interface DragHook {
+  dragged?(props: DragProps): void;
+}
+type DragMixinOptions = DragOptions & ServiceMixinOptions<DragTarget>;
+/**
+ * Subscribe `dragged()` to the drag service for each mount cycle. The root element is the default target.
+ * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
+ */
+declare const withDrag: ServiceMixin<DragHook & ServiceHandles<"dragged">, DragTarget, DragOptions>;
+//#endregion
+export { DRAG_MODES, DragHook, DragMixinOptions, DragMode, DragOptions, DragProps, DragTarget, useDrag, withDrag };