@studiometa/js-toolkit 4.0.0-alpha.1 → 4.0.0-alpha.3

package/dist/context.d.ts

@@ -1,4 +1,3 @@
-//#region src/context.d.ts
 /** A typed context key. `__context` is type-only. */
 type ContextKey<T = unknown> = symbol & {
   readonly __context?: T;
@@ -78,5 +77,4 @@ declare function injectContext<T>(el: Element, key: ContextKey<T>): {
  * @link https://js-toolkit-v4.studiometa.dev/api/context/injectContextSync.html
  */
 declare function injectContextSync<T>(el: Element, key: ContextKey<T>): T | undefined;
-//#endregion
 export { ContextKey, ContextRequest, Signal, cancelContextRequest, createContext, dispatchContextRequest, injectContext, injectContextSync, provideContext, provideRootContext, retainContextRequest, signal };

package/dist/context.js

@@ -1,6 +1,6 @@
 import { getSharedRuntimeSlot } from "./shared-runtime.js";
 import { isolateCallbackFailure } from "./diagnostics.js";
-//#region src/context.ts
+// src/context.ts
 const CONTEXT_REQUEST = "js-toolkit:context:request";
 /**
 * Create a typed context key.
@@ -167,7 +167,6 @@ function injectContextSync(el, key) {
 	});
 	return resolved;
 }
-//#endregion
 export { cancelContextRequest, createContext, dispatchContextRequest, injectContext, injectContextSync, provideContext, provideRootContext, retainContextRequest, signal };
 
 //# sourceMappingURL=context.js.map

package/dist/decorators.d.ts

@@ -1,6 +1,5 @@
 import { ContextKey } from "./context.js";
 import { Base, BaseConfig, BaseConstructor, ChildrenCollection, DelegatedEvent, GlobalEvent, RefEvent, WatchChildrenCallbacks } from "./Base.js";
-//#region src/decorators.d.ts
 /** Decorator syntax requires transpilation; use the function APIs without a build step. */
 type ChildHandler<T extends Base = Base, K extends string = string> = (this: any, payload: DelegatedEvent<T, K>) => void;
 type RefHandler<T extends HTMLElement = HTMLElement> = (this: any, payload: RefEvent<T>) => void;
@@ -66,5 +65,4 @@ declare function inject<T>(key: ContextKey<T>): ValueObserver<T | undefined>;
  */
 declare function children<T extends Base = Base, Host = any>(name: string, callbacks?: WatchChildrenCallbacks<T> & ThisType<Host>): ValueDecorator<ChildrenCollection<T>>;
 declare function children<T extends BaseConstructor, Host = any>(ComponentClass: T, callbacks?: WatchChildrenCallbacks<InstanceType<T>> & ThisType<Host>): ValueDecorator<ChildrenCollection<InstanceType<T>>>;
-//#endregion
 export { children, component, inject, on, provide, read, write };

package/dist/decorators.js

@@ -3,7 +3,7 @@ import { warnOnce } from "./diagnostics.js";
 import { HANDLER_REGISTRATIONS } from "./protocol-symbols.js";
 import { resolveConfig } from "./Base.js";
 import { registerComponent } from "./registry.js";
-//#region src/decorators.ts
+// src/decorators.ts
 /**
 * Global targets use identity checks. Component classes use their merged config name because it is their mount identity.
 * Other `EventTarget` values are invalid because decorators have no component instance or mount cycle.
@@ -183,7 +183,6 @@ function children(target, callbacks) {
 		});
 	};
 }
-//#endregion
 export { children, component, inject, on, provide, read, write };
 
 //# sourceMappingURL=decorators.js.map

package/dist/diagnostic-contract.d.ts

@@ -1,4 +1,3 @@
-//#region src/diagnostic-contract.d.ts
 /**
  * Stable codes carried by toolkit diagnostics.
  * @link https://js-toolkit-v4.studiometa.dev/api/diagnostics/DIAGNOSTICS.html
@@ -100,5 +99,4 @@ type ToolkitDiagnosticDetail = (ToolkitDiagnosticBaseDetail & {
   readonly severity: 'error';
   readonly error: unknown;
 });
-//#endregion
 export { DIAGNOSTICS, ToolkitConsumerDiagnosticCode, ToolkitCoreDiagnosticCode, ToolkitDiagnosticCode, ToolkitDiagnosticDetail, ToolkitDiagnosticSeverity };

package/dist/diagnostic-contract.js

@@ -1,4 +1,4 @@
-//#region src/diagnostic-contract.ts
+// src/diagnostic-contract.ts
 const attribute = Object.freeze({ unknownQualifier: "attribute.unknown-qualifier" });
 const callback = Object.freeze({
 	signalFailed: "callback.signal-failed",
@@ -60,7 +60,6 @@ const DIAGNOSTICS = Object.freeze({
 	storage,
 	swap
 });
-//#endregion
 export { DIAGNOSTICS };
 
 //# sourceMappingURL=diagnostic-contract.js.map

package/dist/diagnostics.d.ts

@@ -1,5 +1,4 @@
 import { ToolkitDiagnosticCode, ToolkitDiagnosticDetail } from "./diagnostic-contract.js";
-//#region src/diagnostics.d.ts
 interface DiagnosticContext {
   component?: string;
   target?: Element;
@@ -37,5 +36,4 @@ declare function warn(code: ToolkitDiagnosticCode, message: string, { component,
  * @internal
  */
 declare function warnOnce(owner: object, key: string, code: ToolkitDiagnosticCode, message: string, context?: DiagnosticContext): CustomEvent<ToolkitDiagnosticDetail> | undefined;
-//#endregion
 export { isolateCallbackFailure, reportDiagnostic, warn, warnOnce };

package/dist/diagnostics.js

@@ -1,5 +1,5 @@
 import { getSharedRuntimeSlot } from "./shared-runtime.js";
-//#region src/diagnostics.ts
+// src/diagnostics.ts
 function warningOwners() {
 	return getSharedRuntimeSlot("diagnostics:warnings", 1, () => ({ owners: /* @__PURE__ */ new WeakMap() })).owners;
 }
@@ -96,7 +96,6 @@ function warnOnce(owner, key, code, message, context) {
 	keys.add(warningKey);
 	return warn(code, message, context);
 }
-//#endregion
 export { isolateCallbackFailure, reportDiagnostic, warn, warnOnce };
 
 //# sourceMappingURL=diagnostics.js.map

package/dist/document-order.d.ts

@@ -1,4 +1,3 @@
-//#region src/document-order.d.ts
 /**
  * Document order, the only order DOM-anchored peers can agree on without
  * either the coordinator or the mount sequence arbitrating it.
@@ -6,5 +5,4 @@
  * Imports nothing, so ordering costs a consumer no component graph.
  */
 declare function compareDocumentOrder(a: Node, b: Node): number;
-//#endregion
 export { compareDocumentOrder };

package/dist/document-order.js

@@ -1,4 +1,4 @@
-//#region src/document-order.ts
+// src/document-order.ts
 /**
 * Document order, the only order DOM-anchored peers can agree on without
 * either the coordinator or the mount sequence arbitrating it.
@@ -11,7 +11,6 @@ function compareDocumentOrder(a, b) {
 	if (position & Node.DOCUMENT_POSITION_PRECEDING) return 1;
 	return 0;
 }
-//#endregion
 export { compareDocumentOrder };
 
 //# sourceMappingURL=document-order.js.map

package/dist/dom-mutations.d.ts

@@ -1,4 +1,3 @@
-//#region src/dom-mutations.d.ts
 interface DOMMutationRecord {
   record: MutationRecord;
   /** Removed subtree membership at observer delivery, before background work. */
@@ -73,5 +72,4 @@ declare function trackDOMLifecycleWork(work: Promise<unknown> | undefined): void
  * @link https://js-toolkit-v4.studiometa.dev/api/dom/whenDOMSettled.html
  */
 declare function whenDOMSettled(): Promise<void>;
-//#endregion
 export { AttributeChange, AttributeWatcher, DOMMutationProcessor, DOMMutationRecord, domVersion, isObservedDOMAttribute, registerDOMOptionAttributes, replaceDOMOptionAttributes, setDOMMutationProcessor, trackDOMLifecycleWork, watchAttributes, whenDOMSettled };

package/dist/dom-mutations.js

@@ -2,7 +2,7 @@ import { FRAMEWORK_ATTRIBUTES, isComponentAttribute, isNetChange, rememberPrevio
 import { getSharedRuntimeSlot } from "./shared-runtime.js";
 import { reportDiagnostic } from "./diagnostics.js";
 import { defaultScheduler } from "./scheduler.js";
-//#region src/dom-mutations.ts
+// src/dom-mutations.ts
 const domMutationState = /* @__PURE__ */ getSharedRuntimeSlot("dom-mutations", 1, () => ({
 	observedAttributes: new Set(FRAMEWORK_ATTRIBUTES),
 	attributeWatchers: /* @__PURE__ */ new Set(),
@@ -232,7 +232,6 @@ async function whenDOMSettled() {
 		if (!domMutationState.processTask && lifecycleWork.size === 0 && (!domMutationState.processor || domMutationState.records.length === 0) && !hasWatchedAttributes()) return;
 	}
 }
-//#endregion
 export { domVersion, isObservedDOMAttribute, registerDOMOptionAttributes, replaceDOMOptionAttributes, setDOMMutationProcessor, trackDOMLifecycleWork, watchAttributes, whenDOMSettled };
 
 //# sourceMappingURL=dom-mutations.js.map

package/dist/events.d.ts

@@ -1,4 +1,3 @@
-//#region src/events.d.ts
 /**
  * Public framework event names.
  * @link https://js-toolkit-v4.studiometa.dev/api/diagnostics/EVENTS.html
@@ -13,5 +12,4 @@ declare const EVENTS: Readonly<{
   }>;
   readonly diagnostic: 'js-toolkit:diagnostic';
 }>;
-//#endregion
 export { EVENTS };

package/dist/events.js

@@ -1,4 +1,4 @@
-//#region src/events.ts
+// src/events.ts
 const component = Object.freeze({
 	mounted: "js-toolkit:component:mounted",
 	unmounted: "js-toolkit:component:unmounted"
@@ -13,7 +13,6 @@ const EVENTS = Object.freeze({
 	dom,
 	diagnostic: "js-toolkit:diagnostic"
 });
-//#endregion
 export { EVENTS };
 
 //# sourceMappingURL=events.js.map

package/dist/group.d.ts

@@ -1,5 +1,4 @@
 import { Signal } from "./context.js";
-//#region src/group.d.ts
 /**
  * What a group needs of a member: the element that decides its rank.
  *
@@ -51,5 +50,4 @@ interface Group<T extends GroupMember = GroupMember> {
  * @link https://js-toolkit-v4.studiometa.dev/api/context/createGroup.html
  */
 declare function createGroup<T extends GroupMember = GroupMember>(): Group<T>;
-//#endregion
 export { Group, GroupMember, createGroup };

package/dist/group.js

@@ -1,6 +1,6 @@
 import { signal } from "./context.js";
 import { compareDocumentOrder } from "./document-order.js";
-//#region src/group.ts
+// src/group.ts
 /**
 * Create an empty group.
 *
@@ -28,7 +28,6 @@ function createGroup() {
 		}
 	};
 }
-//#endregion
 export { createGroup };
 
 //# sourceMappingURL=group.js.map

package/dist/instances.d.ts

@@ -1,5 +1,4 @@
 import { Base } from "./Base.js";
-//#region src/instances.d.ts
 /**
  * Every instance built for a component name, in DOM order, mounted or not.
  *
@@ -82,5 +81,4 @@ declare function getUnmountedInstances<T extends Base = Base>(el: Element): T[];
  * @link https://js-toolkit-v4.studiometa.dev/api/registry/getInstance.html
  */
 declare function getInstance<T extends Base = Base>(el: Element | null, name: string): T | undefined;
-//#endregion
 export { getInstance, getInstances, getMountedInstances, getUnmountedInstances };

package/dist/instances.js

@@ -1,6 +1,6 @@
 import { INSTANCES } from "./protocol-symbols.js";
 import { selectorFor } from "./utils/selectors.js";
-//#region src/instances.ts
+// src/instances.ts
 /**
 * The one traversal behind the three plural lookups.
 *
@@ -65,7 +65,6 @@ function getUnmountedInstances(target, root = document) {
 function getInstance(el, name) {
 	return el?.[INSTANCES]?.get(name);
 }
-//#endregion
 export { getInstance, getInstances, getMountedInstances, getUnmountedInstances };
 
 //# sourceMappingURL=instances.js.map

package/dist/manifest.d.ts

@@ -1,7 +1,6 @@
 import { MountStrategy } from "./mount-strategies.js";
 import { ComponentImporter } from "./Base.js";
 import { ComponentManifest } from "./registry.js";
-//#region src/manifest.d.ts
 /** Lazy module importers keyed by the paths a bundler matched. */
 type ModuleRecord = Record<string, ComponentImporter>;
 /** Options accepted by {@link defineManifest}. */
@@ -32,5 +31,4 @@ declare function fromMetaGlob(glob: Record<string, unknown>): ModuleRecord;
  * @link https://js-toolkit-v4.studiometa.dev/api/registry/fromWebpackContext.html
  */
 declare function fromWebpackContext(context: WebpackContextLike): ModuleRecord;
-//#endregion
 export { DefineManifestOptions, ModuleRecord, WebpackContextLike, defineManifest, fromMetaGlob, fromWebpackContext };

package/dist/manifest.js

@@ -1,5 +1,5 @@
 import { warnOnce } from "./diagnostics.js";
-//#region src/manifest.ts
+// src/manifest.ts
 function deriveToken(path) {
 	const segments = path.split("/").filter((segment) => segment && segment !== ".");
 	const base = (segments.at(-1) ?? "").replace(/\.[^.]+$/, "");
@@ -43,7 +43,6 @@ function fromMetaGlob(glob) {
 function fromWebpackContext(context) {
 	return Object.fromEntries(context.keys().map((key) => [key, () => Promise.resolve(context(key))]));
 }
-//#endregion
 export { defineManifest, fromMetaGlob, fromWebpackContext };
 
 //# sourceMappingURL=manifest.js.map

package/dist/mount-strategies.d.ts

@@ -1,4 +1,3 @@
-//#region src/mount-strategies.d.ts
 /**
  * Control when an instance mounts.
  * `in-view` and `media` are reversible; all other strategies mount once.
@@ -42,5 +41,4 @@ declare function mountStrategyBehaviour(strategy: string): MountStrategyBehaviou
  * Apply a strategy and return its teardown and any eager work that DOM settlement must await.
  */
 declare function applyMountStrategy(el: HTMLElement, strategy: string, { mount, unmount }: MountStrategyHooks): AppliedMountStrategy;
-//#endregion
 export { AppliedMountStrategy, MountStrategy, MountStrategyBehaviour, MountStrategyHooks, applyMountStrategy, mountStrategyBehaviour };

package/dist/mount-strategies.js

@@ -1,6 +1,6 @@
 import { getSharedRuntimeSlot } from "./shared-runtime.js";
 import { defaultScheduler } from "./scheduler.js";
-//#region src/mount-strategies.ts
+// src/mount-strategies.ts
 /** The one scope `interaction` takes; bare `interaction` is the element. */
 const PAGE_SCOPE = "page";
 /**
@@ -207,7 +207,6 @@ function applyMountStrategy(el, strategy, { mount, unmount }) {
 		eagerWork: task.promise
 	};
 }
-//#endregion
 export { applyMountStrategy, mountStrategyBehaviour };
 
 //# sourceMappingURL=mount-strategies.js.map

package/dist/negotiated-events.d.ts

@@ -1,4 +1,3 @@
-//#region src/negotiated-events.d.ts
 /** The DOM change itself: whatever the announcing component was about to do. */
 type DomMutation = () => void | Promise<void>;
 /** An object that can run a DOM change inside a transition. */
@@ -39,5 +38,4 @@ declare function domUpdate(target: Node, mutate: DomMutation, detail?: Record<st
  * @link https://js-toolkit-v4.studiometa.dev/api/dom/emitExtendable.html
  */
 declare function emitExtendable(target: Node, event: string, detail?: Record<string, unknown>): Promise<void>;
-//#endregion
 export { DomMutation, DomUpdateDetail, DomUpdateRunner, DomUpdateTransitioner, ExtendableDetail, ExtendableTransitioner, Extension, domUpdate, emitExtendable };

package/dist/negotiated-events.js

@@ -1,6 +1,6 @@
 import { reportDiagnostic, warnOnce } from "./diagnostics.js";
 import { EVENTS } from "./events.js";
-//#region src/negotiated-events.ts
+// src/negotiated-events.ts
 /** Emit a bubbling event and collect synchronous registrations. */
 function negotiate({ target, event, key, detail, accept }) {
 	let isDispatching = true;
@@ -92,7 +92,6 @@ async function emitExtendable(target, event, detail) {
 	});
 	await Promise.all(pending);
 }
-//#endregion
 export { domUpdate, emitExtendable };
 
 //# sourceMappingURL=negotiated-events.js.map

package/dist/protocol-symbols.d.ts

@@ -1,4 +1,3 @@
-//#region src/protocol-symbols.d.ts
 /** Realm-stable private key with a `unique symbol` type. */
 declare const HANDLER_REGISTRATIONS: unique symbol;
 /**
@@ -20,5 +19,4 @@ declare const HANDLER_REGISTRATIONS: unique symbol;
  * `$0[Symbol.for('@studiometa/js-toolkit/instances')]`.
  */
 declare const INSTANCES: unique symbol;
-//#endregion
 export { HANDLER_REGISTRATIONS, INSTANCES };

package/dist/protocol-symbols.js

@@ -1,4 +1,4 @@
-//#region src/protocol-symbols.ts
+// src/protocol-symbols.ts
 /** Realm-stable private key with a `unique symbol` type. */
 const HANDLER_REGISTRATIONS = Symbol.for("@studiometa/js-toolkit/handler-registrations");
 /**
@@ -20,7 +20,6 @@ const HANDLER_REGISTRATIONS = Symbol.for("@studiometa/js-toolkit/handler-registr
 * `$0[Symbol.for('@studiometa/js-toolkit/instances')]`.
 */
 const INSTANCES = Symbol.for("@studiometa/js-toolkit/instances");
-//#endregion
 export { HANDLER_REGISTRATIONS, INSTANCES };
 
 //# sourceMappingURL=protocol-symbols.js.map

package/dist/registry.d.ts

@@ -1,6 +1,5 @@
 import { MountStrategy } from "./mount-strategies.js";
 import { BaseConstructor, ComponentImporter } from "./Base.js";
-//#region src/registry.d.ts
 /** A lazy component importer and its optional pre-load mount strategy. */
 interface ComponentManifestEntry {
   load: ComponentImporter;
@@ -64,5 +63,4 @@ declare function registerManifest(entries: ComponentManifest): void;
  * ```
  */
 declare function resetRegistry(): void;
-//#endregion
 export { type ComponentImporter, ComponentManifest, ComponentManifestEntry, registerComponent, registerComponents, registerManifest, resetRegistry };

package/dist/registry.js

@@ -11,7 +11,7 @@ import { INSTANCES } from "./protocol-symbols.js";
 import { selectorFor } from "./utils/selectors.js";
 import { declaresBoolean, resolveConfig } from "./Base.js";
 import { applyMountStrategy, mountStrategyBehaviour } from "./mount-strategies.js";
-//#region src/registry.ts
+// src/registry.ts
 observeResponsiveAttribute(COMPONENT_ATTRIBUTE);
 const registryState = /* @__PURE__ */ getSharedRuntimeSlot("registry", 2, () => ({
 	registry: /* @__PURE__ */ new Map(),
@@ -436,7 +436,6 @@ function processMutations(records) {
 	applyOptionChanges(changes);
 	scanAddedNodes(records);
 }
-//#endregion
 export { registerComponent, registerComponents, registerManifest, resetRegistry };
 
 //# sourceMappingURL=registry.js.map

package/dist/responsive-options.d.ts

@@ -1,4 +1,3 @@
-//#region src/responsive-options.d.ts
 /**
  * Exact scoped spellings used by declaration cascades and observer filters.
  * @internal
@@ -30,5 +29,4 @@ declare function responsiveScopedRawValue(attribute: string, breakpoint: string,
 declare function watchBreakpoint(callback: (previous: string) => void): () => void;
 /** Warn once for each responsive attribute suffix that names no breakpoint. */
 declare function checkResponsiveAttributes(el: HTMLElement, attributes: readonly string[]): void;
-//#endregion
 export { activeBreakpoint, checkResponsiveAttributes, observeResponsiveAttribute, responsiveAttributeNames, responsiveRawValue, responsiveScopedRawValue, watchBreakpoint };

package/dist/responsive-options.js

@@ -4,7 +4,7 @@ import { getSharedRuntimeSlot } from "./shared-runtime.js";
 import { warnOnce } from "./diagnostics.js";
 import { registerDOMOptionAttributes, replaceDOMOptionAttributes } from "./dom-mutations.js";
 import { breakpointNames, onBreakpointsReplaced, useBreakpoint } from "./services/breakpoint.js";
-//#region src/responsive-options.ts
+// src/responsive-options.ts
 /**
 * Responsive options cascade from the active breakpoint through narrower breakpoints to the unsuffixed base value.
 *
@@ -100,7 +100,6 @@ function checkResponsiveAttributes(el, attributes) {
 		}
 	}
 }
-//#endregion
 export { activeBreakpoint, checkResponsiveAttributes, observeResponsiveAttribute, responsiveAttributeNames, responsiveRawValue, responsiveScopedRawValue, watchBreakpoint };
 
 //# sourceMappingURL=responsive-options.js.map

package/dist/scheduler.d.ts

@@ -1,4 +1,3 @@
-//#region src/scheduler.d.ts
 type SchedulerPhase = 'idle' | 'tick' | 'read' | 'write' | 'background';
 /** Frame timestamp and elapsed time clamped to `[1, 40]` ms. */
 interface TickProps {
@@ -47,5 +46,4 @@ declare const defaultScheduler: Scheduler;
  * @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

@@ -1,6 +1,6 @@
 import { getSharedRuntimeSlot } from "./shared-runtime.js";
 import { reportDiagnostic } from "./diagnostics.js";
-//#region src/scheduler.ts
+// 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. */
@@ -211,7 +211,6 @@ const defaultScheduler = /* @__PURE__ */ getSharedRuntimeSlot("scheduler:default
 function nextFrame() {
 	return new Promise((resolve) => requestAnimationFrame(() => resolve()));
 }
-//#endregion
 export { Scheduler, defaultScheduler, nextFrame };
 
 //# sourceMappingURL=scheduler.js.map

package/dist/scheduler.js.map

@@ -1 +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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"}
+{"version":3,"file":"scheduler.js","names":[],"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":";;;;AAIA,MAAM,oBAAoB;;AAG1B,MAAM,YAAY;AAClB,MAAM,YAAY;;AAGlB,MAAM,gBAAgB,MAAO;;AAO7B,MAAM,eAAe,CAAC,QAAQ,OAAO;;AAWrC,MAAM,QAA2B,CAAC;AAClC,IAAI;;AAGJ,SAAS,gBAAgB,KAAuB;CAE9C,IAAI,CAAC,SAAS;EACZ,UAAU,IAAI,eAAe;EAC7B,QAAQ,MAAM,kBAAkB,MAAM,MAAM,CAAC,GAAG;CAClD;CACA,MAAM,KAAK,GAAG;CACd,QAAQ,MAAM,YAAY,IAAI;AAChC;AAEA,SAAS,mBAAmB,KAAuB;CAEjD,MAAM,kBAAkB,WAAW;CACnC,IAAI,OAAO,iBAAiB,aAAa,YAAY;EACnD,gBAAgB,SAAS,KAAK,EAAE,UAAU,aAAa,CAAC,CAAC,CAAC,OAAO,UAAmB;GAClF,iBACE,oCACA,oDACA,KACF;GACA,gBAAgB,GAAG;EACrB,CAAC;EACD;CACF;CAEA,gBAAgB,GAAG;AACrB;;;;;;AAuBA,IAAa,YAAb,MAAuB;CACrB,UAA0C;EACxC,MAAM,CAAC;EACP,OAAO,CAAC;EACR,YAAY,CAAC;CACf;CAEA,SAAyB;CAEzB,eAAe;CAEf,yBAAyB;CAEzB,iBAAoC,CAAC;CAErC,iCAAiB,IAAI,IAAkB;;;;;CAMvC,iBAAiB;CAEjB,IAAI,QAAwB;EAC1B,OAAO,KAAK;CACd;;;;;;CAOA,KAAK,UAAoC;EACvC,IAAI,KAAK,eAAe,SAAS,GAC/B,KAAK,iBAAiB;EAExB,KAAK,eAAe,IAAI,QAAQ;EAChC,KAAK,UAAU;EACf,aAAa;GACX,KAAK,eAAe,OAAO,QAAQ;EACrC;CACF;CAEA,KAAQ,IAA+B;EACrC,OAAO,KAAK,KAAK,QAAQ,EAAE;CAC7B;CAEA,MAAS,IAA+B;EACtC,OAAO,KAAK,KAAK,SAAS,EAAE;CAC9B;;CAGA,WAAc,IAA+B;EAC3C,OAAO,KAAK,KAAK,cAAc,EAAE;CACnC;;;;CAKA,WAA0B;EACxB,IAAI,KAAK,QAAQ,GACf,OAAO,QAAQ,QAAQ;EAEzB,OAAO,IAAI,SAAS,YAAY,KAAK,eAAe,KAAK,OAAO,CAAC;CACnE;;;;;;CAOA,UAAmB;EACjB,OAAO,OAAO,OAAO,KAAK,OAAO,CAAC,CAAC,OAAO,UAAU,MAAM,WAAW,CAAC;CACxE;CAEA,KAAQ,WAAsB,IAA+B;EAC3D,IAAI;EACJ,IAAI;EACJ,MAAM,UAAU,IAAI,SAAS,KAAK,QAAQ;GACxC,UAAU;GACV,SAAS;EACX,CAAC;EAGD,QAAQ,YAAY,CAAC,CAAC;EACtB,MAAM,OAAkB;GAAE;GAAI,YAAY;GAAO;GAAS;EAAO;EACjE,KAAK,QAAQ,UAAU,CAAC,KAAK,IAAI;EACjC,IAAI,cAAc,cAChB,KAAK,oBAAoB;OAEzB,KAAK,UAAU;EAEjB,OAAO;GACI;GACT,SAAS;IACP,KAAK,aAAa;GACpB;EACF;CACF;CAEA,YAAkB;EAChB,IAAI,KAAK,cACP;EAEF,KAAK,eAAe;EAEpB,uBAAuB,cAAc,KAAK,OAAO,SAAS,CAAC;CAC7D;CAEA,sBAA4B;EAC1B,IAAI,KAAK,wBACP;EAEF,KAAK,yBAAyB;EAC9B,yBAAyB,KAAK,iBAAiB,CAAC;CAClD;;;;;;CAOA,mBAAyB;EACvB,KAAK,yBAAyB;EAC9B,MAAM,QAAQ,YAAY,IAAI;EAC9B,MAAM,QAAQ,KAAK,QAAQ;EAE3B,KAAK,SAAS;EACd,OAAO,MAAM,SAAS,KAAK,YAAY,IAAI,IAAI,QAAQ,mBACrD,KAAK,KAAK,MAAM,MAAM,CAAc;EAEtC,KAAK,SAAS;EAEd,IAAI,MAAM,SAAS,GACjB,KAAK,oBAAoB;EAE3B,KAAK,aAAa;CACpB;CAEA,OAAO,WAAsC;EAC3C,KAAK,eAAe;EAEpB,IAAI,KAAK,eAAe,OAAO,GAAG;GAChC,KAAK,SAAS;GACd,MAAM,QAAmB;IACvB,MAAM;IACN,OAAO,KAAK,YAAY,SAAS;GACnC;GACA,KAAK,iBAAiB;GACtB,MAAM,YAAY,CAAC,GAAG,KAAK,cAAc;GACzC,KAAK,MAAM,YAAY,WAAW;IAGhC,IAAI,CAAC,KAAK,eAAe,IAAI,QAAQ,GACnC;IAEF,IAAI;KACF,SAAS,KAAK;IAChB,SAAS,OAAO;KAGd,iBACE,kCACA,qCACA,KACF;IACF;GACF;EACF;EAGA,KAAK,MAAM,SAAS,cAAc;GAChC,KAAK,SAAS;GACd,MAAM,QAAQ,KAAK,QAAQ;GAC3B,KAAK,QAAQ,SAAS,CAAC;GACvB,KAAK,MAAM,QAAQ,OACjB,KAAK,KAAK,IAAI;EAElB;EAEA,KAAK,SAAS;EAId,IAAI,KAAK,cAAc,KAAK,KAAK,eAAe,OAAO,GACrD,KAAK,UAAU;EAEjB,KAAK,aAAa;CACpB;CAEA,gBAAyB;EACvB,OAAO,aAAa,MAAM,UAAU,KAAK,QAAQ,MAAM,CAAC,SAAS,CAAC;CACpE;CAEA,YAAY,WAAwC;EAClD,IAAI,KAAK,iBAAiB,GACxB,OAAO;EAET,OAAO,KAAK,IAAI,KAAK,IAAI,YAAY,KAAK,gBAAgB,SAAS,GAAG,SAAS;CACjF;CAEA,eAAqB;EACnB,IAAI,KAAK,eAAe,WAAW,KAAK,CAAC,KAAK,QAAQ,GACpD;EAEF,MAAM,YAAY,KAAK;EACvB,KAAK,iBAAiB,CAAC;EACvB,KAAK,MAAM,WAAW,WACpB,QAAQ;CAEZ;CAEA,KAAK,MAAuB;EAC1B,IAAI,KAAK,YAAY;GACnB,KAAK,QAAQ,KAAA,CAAS;GACtB;EACF;EACA,IAAI;GACF,KAAK,QAAQ,KAAK,GAAG,CAAC;EACxB,SAAS,OAAO;GAGd,iBAAiB,kCAAkC,4BAA4B,KAAK;GACpF,KAAK,OAAO,KAAK;EACnB;CACF;AACF;;;;;AAMA,MAAa,mBAAmC,qCAC9C,qBACA,SACM,IAAI,UAAU,CACtB;;;;;AAMA,SAAgB,YAA2B;CACzC,OAAO,IAAI,SAAS,YAAY,4BAA4B,QAAQ,CAAC,CAAC;AACxE"}

package/dist/services/breakpoint.d.ts

@@ -1,5 +1,4 @@
 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
@@ -31,5 +30,4 @@ declare function onBreakpointsReplaced(callback: () => void): () => void;
  * @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

@@ -1,7 +1,7 @@
 import { memo } from "../utils/memo.js";
 import { getSharedRuntimeSlot } from "../shared-runtime.js";
 import { createService } from "./service.js";
-//#region src/services/breakpoint.ts
+// 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
@@ -124,7 +124,6 @@ function useBreakpoint() {
 	breakpointState.service ??= createBreakpointService();
 	return breakpointState.service;
 }
-//#endregion
 export { BREAKPOINTS, breakpointNames, getBreakpoints, onBreakpointsReplaced, setBreakpoints, useBreakpoint };
 
 //# sourceMappingURL=breakpoint.js.map

package/dist/services/drag.d.ts

@@ -1,6 +1,5 @@
 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;
 /**
@@ -61,5 +60,4 @@ type DragMixinOptions = DragOptions & ServiceMixinOptions<DragTarget>;
  * @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 };

package/dist/services/drag.js

@@ -3,7 +3,7 @@ import { defaultScheduler } from "../scheduler.js";
 import { createService, perTarget } from "./service.js";
 import { INERTIA_FRAME, clampDampFactor, inertiaDecay, inertiaFinalValue, inertiaStep } from "../utils/maths.js";
 import { createServiceMixin } from "./mixin.js";
-//#region src/services/drag.ts
+// src/services/drag.ts
 /**
 * Drag lifecycle modes: `idle → start → drag → drop → inertia → stop → idle`.
 * @link https://js-toolkit-v4.studiometa.dev/api/services/useDrag.html
@@ -265,7 +265,6 @@ const withDrag = /* @__PURE__ */ createServiceMixin({
 	target: (instance) => instance.$el,
 	use: (target, options) => useDrag(target, options)
 });
-//#endregion
 export { DRAG_MODES, useDrag, withDrag };
 
 //# sourceMappingURL=drag.js.map

package/dist/services/in-view.d.ts

@@ -1,6 +1,5 @@
 import { Service } from "./service.js";
 import { ServiceHandles, ServiceMixin, ServiceMixinOptions } from "./mixin.js";
-//#region src/services/in-view.d.ts
 interface InViewProps {
   /** Whether the target intersects its root, as the latest entry reports it. */
   readonly isInView: boolean;
@@ -22,5 +21,4 @@ type InViewMixinOptions = IntersectionObserverInit & ServiceMixinOptions<Element
  * @link https://js-toolkit-v4.studiometa.dev/api/services/mixins.html
  */
 declare const withInView: ServiceMixin<InViewHook & ServiceHandles<"intersected">, Element, IntersectionObserverInit>;
-//#endregion
 export { InViewHook, InViewMixinOptions, InViewProps, useInView, withInView };

package/dist/services/in-view.js

@@ -1,7 +1,7 @@
 import { getSharedRuntimeSlot } from "../shared-runtime.js";
 import { createService, perTarget, stableKey } from "./service.js";
 import { createServiceMixin } from "./mixin.js";
-//#region src/services/in-view.ts
+// src/services/in-view.ts
 /** Give each observer root a stable serializable identity. */
 function rootId(root, identity) {
 	let id = identity.ids.get(root);
@@ -77,7 +77,6 @@ const withInView = /* @__PURE__ */ createServiceMixin({
 	defaultImmediate: true,
 	use: (target, options) => useInView(target, options)
 });
-//#endregion
 export { useInView, withInView };
 
 //# sourceMappingURL=in-view.js.map