@pacem/pacem-core 1.0.0-bernoulli → 1.0.0-binet

package/typings/index.d.ts

@@ -7,28 +7,52 @@ import { Point } from '@pacem/pacem-foundation';
 import { Rect } from '@pacem/pacem-foundation';
 import { Strings } from '@pacem/pacem-foundation';
 
+/**
+ * Abstract base class for the `@CustomElement` animation items (color/number/point animations) that can be
+ * hosted within a {@link PacemStoryboardElement}. Implements {@link Timeline}.
+ */
 declare abstract class AnimationElement extends PacemItemElement implements Timeline {
+    /** Gets or sets the element whose property is animated. */
     target: Element;
+    /** Gets or sets the name of the animated property on `target`. */
     property: string;
+    /** Gets or sets the delay before the animation starts, in milliseconds. */
     delay: number;
+    /** Gets or sets the animation duration, in milliseconds. */
     duration: number;
+    /** Gets or sets the easing function applied to the animation progress; accepts any key of {@link Easings} and defaults to linear. */
     easing: Easing;
+    /** Gets or sets the number of times the animation repeats. */
     iterations: number;
+    /** Gets or sets the playback direction of the animation. */
     direction: PlaybackDirection;
+    /** Gets or sets the starting value of the animated property. */
     abstract from: any;
+    /** Gets or sets the ending value of the animated property. */
     abstract to: any;
+    /** Starts (or restarts) the animation and returns a promise resolved once it completes. */
     abstract startAnimation(): Promise<void>;
+    /** Cancels the running animation. */
     abstract cancelAnimation(): void;
 }
 
+/**
+ * `end` event dispatched once a tween/animation completes.
+ */
 declare class AnimationEndEvent extends CustomEvent<{}> {
     constructor();
 }
 
+/**
+ * `step` event dispatched on every animation frame of a running tween, carrying the current progress and value.
+ */
 declare class AnimationEvent_2 extends CustomTypedEvent<AnimationEventArgs> {
     constructor(args: AnimationEventArgs);
 }
 
+/**
+ * Plain data shape carried by {@link AnimationEvent}: the normalized progress and the current interpolated value.
+ */
 declare type AnimationEventArgs = {
     time: number;
     value: number;
@@ -48,6 +72,9 @@ export declare namespace Animations {
     }
 }
 
+/**
+ * `start` event dispatched when a tween/animation begins.
+ */
 declare class AnimationStartEvent extends CustomEvent<{}> {
     constructor();
 }
@@ -65,19 +92,30 @@ declare interface AriaAttributes {
     };
 }
 
+/**
+ * Dispatched by elements registered with the {@link CustomElement} decorator whenever one of their
+ * observed attributes changes, mirroring the native `attributeChangedCallback` as a DOM event.
+ */
 export declare class AttributeChangeEvent extends CustomTypedEvent<AttributeChangeEventArgs> {
     constructor(args: AttributeChangeEventArgs);
 }
 
+/** Payload carried by an {@link AttributeChangeEvent}. */
 export declare interface AttributeChangeEventArgs {
+    /** Name of the attribute that changed (as written in markup, i.e. kebab-case). */
     attributeName: string;
+    /** Attribute's previous string value, if any. */
     oldValue?: string;
+    /** Attribute's new string value. */
     currentValue: string;
+    /** `true` when this is the attribute's first observed value (element not fully initialized yet). */
     firstChange?: boolean;
 }
 
+/** Event name dispatched whenever an observed attribute changes; see {@link AttributeChangeEvent}. */
 export declare const AttributeChangeEventName: string;
 
+/** Ready-to-use event listener that calls both `evt.preventDefault()` and `evt.stopPropagation()`. */
 export declare const avoidHandler: (evt: Event) => void;
 
 export declare namespace Behaviors {
@@ -86,15 +124,23 @@ export declare namespace Behaviors {
     }
 }
 
+/**
+ * Bubbling, cancelable event representing a generic UI command (e.g. a button's `command`/`command-argument`
+ * attributes), letting ancestor elements handle named actions without wiring a dedicated listener per command.
+ */
 export declare class CommandEvent extends CustomTypedEvent<CommandEventArgs> {
     constructor(args: CommandEventArgs);
 }
 
+/** Payload carried by a {@link CommandEvent}. */
 export declare type CommandEventArgs = {
+    /** Name identifying the command being invoked. */
     commandName: string;
+    /** Optional argument accompanying the command. */
     commandArgument: any;
 };
 
+/** Event name dispatched to signal a generic, named command invocation; see {@link CommandEvent}. */
 export declare const CommandEventName: string;
 
 export declare namespace Components {
@@ -142,11 +188,6 @@ export declare namespace Components {
         ResizeEventArgs,
         ResizeEvent,
         PacemResizeElement,
-        RouterNavigatingEventName,
-        RouterNavigateEventName,
-        RouterNavigateEventArgs,
-        RouterNavigateEvent,
-        RouterNavigatingEvent,
         PacemRouterElement,
         ScrollEventName,
         ScrollEventArgs,
@@ -191,6 +232,15 @@ export declare namespace Components {
     }
 }
 
+/**
+ * Method decorator that serializes calls to an async (promise-returning) method on a per-instance basis:
+ * while an invocation is in flight, further calls are queued (their arguments buffered) instead of running
+ * concurrently, and each queued call gets its own promise that resolves/rejects once it eventually runs.
+ * Once the in-flight call settles, the oldest buffered call (if any) is dequeued and executed next.
+ * Methods that don't return a promise-like value are simply invoked synchronously with no queuing.
+ *
+ * @returns A method decorator to apply to an async instance method.
+ */
 export declare function Concurrent(): (target: any, key: string, descriptor?: PropertyDescriptor) => void;
 
 /** To be replaced when Cookie Store API types will be included in TypeScript. */
@@ -206,6 +256,7 @@ export declare type CookieData = {
     secure?: boolean;
 };
 
+/** Minimal shape of the (currently non-standard) `window.cookieStore` API, used by {@link Utils.Cookies} when available. */
 export declare type CookieStoreLike = {
     delete(c: string | CookieData): Promise<void>;
     get(c: string): Promise<CookieData>;
@@ -215,12 +266,39 @@ export declare type CookieStoreLike = {
     removeEventListener: (type: 'change', handler: EventListener) => void;
 };
 
+/** Dispatched by an {@link Iterative} container whenever its `index` changes. */
 export declare class CurrentIndexChangeEvent extends CustomTypedEvent<IndexChangeEventArgs> {
     constructor(args: IndexChangeEventArgs);
 }
 
+/**
+ * Class decorator that turns a class extending `HTMLElement` (typically {@link PacemEventTarget}) into a
+ * fully-fledged Pacem custom element: it registers the tag with the custom elements registry and wraps
+ * the standard `connectedCallback`/`disconnectedCallback`/`attributeChangedCallback`/`propertyChangedCallback`
+ * lifecycle hooks (calling through to any hooks already defined on the class) so that:
+ *
+ * - `observedAttributes` is computed automatically from the class's {@link Watch}-decorated properties
+ *   (in kebab-case), merged with any statically-declared `observedAttributes`.
+ * - On first connection, `config.template`/`config.templateUrl` (if provided) is fetched, parsed and
+ *   injected — into a Shadow Root when `config.shadow` is `true`, otherwise as light-DOM children,
+ *   splicing any pre-existing light-DOM content into a `<pacem-content>` placeholder if present.
+ * - Attribute changes are converted to property values via each watched property's {@link PropertyConverter},
+ *   and dispatched as an {@link AttributeChangeEvent}.
+ * - Property changes are dispatched as a {@link PropertyChangeEvent} (unless the property's `@Watch`
+ *   config sets `emit: false`) and, when `reflectBack` is enabled, written back onto the corresponding
+ *   attribute via the converter's `convertBack`.
+ * - Binding expression attributes (`{{ ... }}`) are parsed and kept live: dependent properties are
+ *   re-evaluated whenever one of the expression's upstream properties fires a {@link PropertyChangeEvent}.
+ * - Once the template (and all descendant templated custom elements) have finished rendering, the
+ *   `cloak` attribute is removed and `viewActivatedCallback` fires — this is the right place for logic
+ *   that depends on the element's full DOM (light or shadow) being in place.
+ *
+ * @param config Tag name, optional native `customElements.define` options, and optional template/templateUrl/shadow settings.
+ * @returns A class decorator to apply to the custom element's class declaration.
+ */
 export declare const CustomElement: (config: CustomElementConfig) => (target: Type<any>) => void;
 
+/** Configuration options accepted by the {@link CustomElement} class decorator. */
 export declare type CustomElementConfig = {
     tagName: string;
     options?: {
@@ -234,6 +312,7 @@ export declare type CustomElementConfig = {
     shadow?: boolean;
 };
 
+/** Minimal shape of the (native or polyfilled) `CustomElementRegistry` used by {@link Utils.customElements} to define and look up custom elements. */
 declare interface CustomElementRegistry_2 {
     define(name: string, type: Type<any>, options?: {
         [key: string]: string;
@@ -243,10 +322,31 @@ declare interface CustomElementRegistry_2 {
 }
 export { CustomElementRegistry_2 as CustomElementRegistry }
 
+/**
+ * Static grab-bag of low-level helpers underpinning the {@link CustomElement}/{@link Watch} decorators
+ * and the binding-expression engine: attached-property storage (a per-instance, non-enumerable "bag"
+ * used instead of expando properties), attribute/property name conversion, DOM tree traversal, host/
+ * scope resolution for templated content, and binding-attribute parsing.
+ */
 export declare class CustomElementUtils {
+    /** `true` when the platform's `customElements` registry is the Custom Elements polyfill rather than a native implementation. */
     static get polyfilling(): boolean;
+    /** Converts a camelCase property name to its kebab-case attribute-name equivalent (e.g. `myProp` → `my-prop`). */
     static camelToKebab(camelCased: string): string;
+    /** Converts a kebab-case attribute name to its camelCase property-name equivalent (e.g. `my-prop` → `myProp`). */
     static kebabToCamel(kebabCased: string): string;
+    /** Waits for the specified alement to be ready. */
+    static waitForReady(element: PacemEventTarget): Promise<void>;
+    /** Waits for the specified element to be ready, then executes the provided callback. */
+    static whenReady(element: PacemEventTarget, callback: () => void): void;
+    /**
+     * Retrieves the `@Watch`-decorated property descriptors declared on a custom element class (or an
+     * instance thereof), walking up the prototype chain when `includeInherited` is `true` (the default).
+     * Properties whose name starts with `_` are treated as private and excluded.
+     * @param target Element class, or an element instance (its constructor is used).
+     * @param includeInherited Whether to include properties declared on base classes. Defaults to `true`.
+     * @returns The watched property descriptors, base classes first.
+     */
     static getWatchedProperties(target: Type<any>, includeInherited?: boolean): {
         name: string;
         config: WatchConfig;
@@ -255,20 +355,59 @@ export declare class CustomElementUtils {
         name: string;
         config: WatchConfig;
     }[];
+    /** Retrieves a single `@Watch`-decorated property descriptor by name; see {@link getWatchedProperties}. */
     static getWatchedProperty(target: HTMLElement, name: string): {
         name: string;
         config: WatchConfig;
     };
+    /**
+     * Loads a `<script>` tag once (deduplicated by `src`, cached via {@link import}), resolving when it fires `load`.
+     * @param src Script URL.
+     * @param integrity Optional Subresource Integrity hash.
+     * @param crossorigin Whether to set `crossorigin` on the tag.
+     */
     static importjs(src: string, integrity?: string, crossorigin?: boolean): Promise<HTMLElement>;
+    /**
+     * Loads a `<link rel="stylesheet">` tag once (deduplicated by `src`, cached via {@link import}), resolving when it fires `load`.
+     * @param src Stylesheet URL.
+     * @param integrity Optional Subresource Integrity hash.
+     * @param crossorigin Whether to set `crossorigin="anonymous"` on the tag.
+     */
     static importcss(src: string, integrity?: string, crossorigin?: boolean): Promise<HTMLElement>;
+    /**
+     * Creates (or reuses an already-present, matching) element of `tagName` with the given attributes and
+     * appends it to the DOM, returning a promise that resolves once it loads (or rejects on error). Results
+     * are cached per `key` (under `Utils.core.imports`) so repeated calls with the same key are a no-op.
+     * @param key Cache/dedupe key (typically the resource URL).
+     * @param tagName Tag name of the element to create (e.g. `'script'`, `'link'`).
+     * @param attrs Attributes to set on the element, also used to build a matching CSS selector to detect a pre-existing element.
+     * @param appendTo Node to append the newly created element to, if none was found. Defaults to `document.body`.
+     */
     static import(key: string, tagName: string, attrs: {
         [name: string]: any;
     }, appendTo?: Node): Promise<HTMLElement>;
+    /** Theming-related helpers. */
     static Theme: {
+        /** Downloads the web fonts referenced by the current theme's `--{@link PCSS}-font-*` CSS custom properties, resolving once at least one font face is ready (or after a short timeout). */
         importWebFonts(): Promise<any>;
     };
+    /**
+     * Stores an arbitrary value "attached" to `target` under `name`, in a private, non-enumerable bag
+     * (rather than as a plain expando property) so it doesn't show up in `for...in`/`Object.keys`/JSON
+     * serialization. Setting `value` to `null`/`undefined` removes the entry. See {@link getAttachedPropertyValue}.
+     * @param target Object to attach the value to.
+     * @param name Key under which the value is stored.
+     * @param value Value to store, or `null`/`undefined` to remove the entry.
+     */
     static setAttachedPropertyValue(target: any, name: string, value: any): void;
+    /** Removes a value previously stored via {@link setAttachedPropertyValue}. */
     static deleteAttachedPropertyValue(target: any, name: string): void;
+    /**
+     * Reads a value previously stored via {@link setAttachedPropertyValue}.
+     * @param target Object the value is attached to.
+     * @param name Key the value is stored under.
+     * @param ensureValue If provided and no value is currently stored, this value is stored and returned (lazy-initialization).
+     */
     static getAttachedPropertyValue(target: any, name: string, ensureValue?: any): any;
     /**
      * Resolves a dotted path into actual values.
@@ -289,19 +428,60 @@ export declare class CustomElementUtils {
             property: string;
         };
     };
+    /**
+     * Writes `value` at the given dotted `path`, rooted at `element` (see {@link resolvePath}), triggering
+     * the appropriate `propertychange` notification. For paths nested more than one level deep (and not
+     * targeting an `HTMLElement`, which fires change notifications autonomously), the whole root property
+     * is cloned, mutated and reassigned so that a `propertychange` fires with meaningful old/new values -
+     * a plain nested assignment wouldn't otherwise be observed. Repeater-bound `item` paths are special-cased
+     * to update the owning {@link Repeater}'s `datasource` array in place.
+     * @param element Root element the path is resolved against.
+     * @param path Dotted path (e.g. `'foo.bar[0].baz'`) to the target property.
+     * @param value New value to assign.
+     */
     static set(element: Node, path: string, value: any): void;
+    /** Reads the value at the given dotted `path`, rooted at `element`; see {@link resolvePath}. */
     static get(element: Node, path: string): any;
     /**
      * Works for unit-test contexts.
      * @param element
      */
     private static _findScopeContextLegacy;
+    /**
+     * Finds the `Document` or `ShadowRoot` that `element` belongs to - used as the root for resolving
+     * scoped binding expressions (e.g. `$document`/`$host` lookups). Falls back to the previously-attached
+     * scope value (see `INSTANCE_SCOPE_VAR`, set on `connectedCallback`) when `element` is currently
+     * disconnected, and to a legacy manual-walk implementation as a last resort (needed under Jasmine tests,
+     * where `element.isConnected` never reports `true`).
+     * @param element Element to resolve the containing document/shadow-root scope for.
+     */
     static findScopeContext(element: HTMLElement): Document | ShadowRoot;
+    /**
+     * Walks up from `element` (crossing shadow-root boundaries via the host element) looking for the
+     * first ancestor matching `predicate`.
+     * @param element Element to start the upward search from.
+     * @param predicate Test invoked (as `this`-bound and argument-passed) against each ancestor.
+     * @returns The first matching ancestor, or `undefined` if none matches.
+     */
     static findAncestor(element: Element, predicate: (Node: any) => boolean): any;
+    /** Finds the nearest ancestor "shell" element - matching `.{@link PCSS}-body` - or falls back to `document.body`; see {@link findAncestor}. */
     static findAncestorShell(element: Element): HTMLElement;
+    /** Finds the nearest ancestor that is an instance of `ctor`; see {@link findAncestor}. */
     static findAncestorOfType<TNode extends Node>(element: Element, ctor: Type<TNode>): TNode;
+    /**
+     * Collects the descendants of `element` matching `predicate`, via a `TreeWalker` over element nodes.
+     * @param element Root element to search from (exclusive - the walker starts on its descendants).
+     * @param predicate Test invoked against each descendant element.
+     * @param firstOnly When `true`, stops and returns as soon as one match is found.
+     */
     static findDescendants(element: Element, predicate: (Node: any) => boolean, firstOnly?: boolean): Node[];
+    /** Finds the first descendant of `element` matching `predicate`, or `undefined` if none matches; see {@link findDescendants}. */
     static findFirstDescendant(element: Element, predicate: (Node: any) => boolean): Node;
+    /**
+     * Queries the whole document for elements matching `selector`, additionally filtered by `filter`.
+     * @param selector CSS selector to query for. Defaults to `'[pacem]'` (every Pacem custom element, which all carry that attribute once connected).
+     * @param filter Extra predicate applied to each matched element. Defaults to accepting everything.
+     */
     static findAll<T extends Element>(selector?: string, filter?: (e: Element) => boolean): T[];
     /**
      * To be used back again when Edge will allow Comment subclassing
@@ -319,11 +499,43 @@ export declare class CustomElementUtils {
      * @param upLevels
      */
     static findPreviousSiblingOrAncestor(element: Element, predicate: (Node: any) => boolean, upLevels?: number): Node;
+    /**
+     * Tags every element/document-fragment node inside `template`'s content (that isn't already tagged)
+     * with `host` under `INSTANCE_HOST_VAR`, so that once cloned and inserted into the DOM, binding
+     * expressions in that fragment can resolve back to the custom element instance ("host") that owns
+     * this template. See {@link findHostContext}.
+     * @param host The custom element instance whose template this is.
+     * @param template Template whose content's descendants should be tagged.
+     */
     static assignHostContext(host: any, template: HTMLTemplateElement): void;
+    /**
+     * Walks up from `element` looking for the nearest ancestor (inclusive) tagged with a host reference
+     * via {@link assignHostContext}; this is the custom element instance whose template produced `element`,
+     * used to resolve `$host`/scope references in binding expressions. Returns `undefined` (with a console
+     * warning) if `element` is disconnected or isn't part of any templated component.
+     * @param element Element to resolve the owning host for.
+     */
     static findHostContext(element: HTMLElement): HTMLElement;
+    /** Tests whether an attribute's raw string value has binding-expression syntax (`{{ ... }}`). */
     static isBindingAttribute(attr: string): boolean;
+    /** Strips the `{{ }}` delimiters off a binding attribute's raw value, returning the bare expression text. Throws if `attr` isn't a valid binding attribute; see {@link isBindingAttribute}. */
     static extractBindingAttributeExpression(attr: string): string;
+    /**
+     * Parses a `{{ ... }}` binding attribute value into an {@link Expression}, recognizing the optional
+     * trailing `, twoway` / `, once` modifier and stamping it onto the expression's dependencies (`twoway`
+     * only applies when the expression has exactly one dependency that itself allows two-way binding).
+     * @param attr Raw binding attribute value, including the `{{ }}` delimiters.
+     * @param element Element the expression is evaluated/bound against (used to resolve scope references).
+     */
     static parseBindingAttribute(attr: string, element: HTMLElement): Expression;
+    /**
+     * Defines an own property `name` on `o` with `attributes`, unless `o` already has an own property
+     * descriptor for that name (in which case the existing descriptor is returned untouched).
+     * @param o Object to define the property on.
+     * @param name Property name.
+     * @param attributes Property descriptor to apply if the property isn't already defined.
+     * @returns The (possibly pre-existing) property descriptor.
+     */
     static ensureMember(o: any, name: string, attributes: PropertyDescriptor): PropertyDescriptor;
     /**
      * Strips all the observed attributes of an element and its descendants, in order to seal that dom branch and to avoid bindings evaluation.
@@ -337,9 +549,27 @@ export declare class CustomElementUtils {
     static freezeObservedAttributes(element: Element): void;
 }
 
+/** Static helpers for inspecting and normalizing native/custom events (coordinates, keyboard modifiers, type checks). */
 export declare class CustomEventUtils {
+    /**
+     * Type-guarding check for whether `evt` is an instance of the given event `type`.
+     * @param evt Event to test.
+     * @param type Event constructor to test against.
+     * @returns `true` (narrowing `evt` to `TEvent`) if `evt instanceof type`.
+     */
     static isInstanceOf<TEvent extends Event>(evt: Event, type: Type<TEvent>): evt is TEvent;
+    /**
+     * Extracts page/client/screen coordinates from a mouse or (single-)touch event, using the first
+     * active touch (`touches[0]`, falling back to `changedTouches[0]`) for `TouchEvent`s.
+     * @param evt Source mouse/touch event, or an already-extracted {@link UIEventLike}.
+     * @returns The event's position in all three coordinate systems.
+     */
     static getEventCoordinates(evt: MouseEvent | TouchEvent | UIEventLike): EventCoordinates;
+    /**
+     * Extracts the keyboard-modifier flags (and, for mouse events, the pressed button as `which`) from a native event.
+     * @param evt Source keyboard/mouse/touch event, or an already-extracted {@link KeyEventLike}.
+     * @returns The captured modifier flags.
+     */
     static getEventKeyModifiers(evt: KeyboardEvent | MouseEvent | TouchEvent | KeyEventLike): EventKeyModifiers;
     /**
      * Matches the provided event against keyboard modifiers and returns 'true' if all the matches are satisfied.
@@ -348,6 +578,13 @@ export declare class CustomEventUtils {
      */
     static matchModifiers(evt: KeyboardEvent | MouseEvent | TouchEvent | KeyEventLike, modifiers: string[]): any;
     static matchModifiers(evt: KeyboardEvent | MouseEvent | TouchEvent | KeyEventLike, ...modifiers: EventKeyModifier[]): any;
+    /**
+     * Works around a legacy Edge/ChakraCore bug (see {@link https://github.com/Microsoft/ChakraCore/issues/3952})
+     * where an instance built via `super(...)` from a `CustomEvent` subclass constructor doesn't correctly
+     * pass `instanceof` checks against that subclass; forcibly resets its prototype when so.
+     * @param evt Event instance to fix up.
+     * @param type The subclass constructor `evt` is supposed to be an instance of.
+     */
     static fixEdgeCustomEventSubClassInstance<TEvent extends Event>(evt: TEvent, type: Function): void;
 }
 
@@ -355,10 +592,27 @@ declare class CustomItemCommandEvent extends ItemEvent<any> {
     constructor(evt: CommandEvent);
 }
 
+/**
+ * Base class for framework custom events whose `detail` payload is strongly typed as `TDetail`.
+ * Thin wrapper around the native `CustomEvent<TDetail>` that also works around an old Edge bug
+ * (see {@link CustomEventUtils.fixEdgeCustomEventSubClassInstance}) affecting `CustomEvent` subclasses.
+ */
 export declare abstract class CustomTypedEvent<TDetail> extends CustomEvent<TDetail> {
+    /**
+     * @param type Event name.
+     * @param detail Strongly-typed payload, exposed as `event.detail`.
+     * @param eventInit Standard `CustomEvent` initialization options (`bubbles`, `cancelable`, `composed`).
+     */
     constructor(type: string, detail: TDetail, eventInit?: CustomEventInit<TDetail>);
 }
 
+/**
+ * Base class for UI-originated custom events: like {@link CustomTypedEvent}, but additionally captures
+ * the mouse/touch/keyboard modifiers and coordinates of the originating native event (when supplied),
+ * exposing them through the {@link UIEventLike} surface (`which`, `altKey`, `pageX`, `clientY`, ...).
+ * Useful for events that are re-dispatched/synthesized (e.g. drag & drop) from an original pointer or
+ * keyboard event, so that consumers can still inspect that original event's modifiers/position.
+ */
 export declare abstract class CustomUIEvent<TDetail> extends CustomEvent<TDetail> implements UIEventLike {
     #private;
     constructor(type: string, detail: TDetail);
@@ -381,10 +635,26 @@ export declare abstract class CustomUIEvent<TDetail> extends CustomEvent<TDetail
     get screenY(): number;
 }
 
+/**
+ * Method decorator that debounces calls to an instance method: repeated calls within the debounce window
+ * cancel the previously scheduled invocation and reschedule it, so only the last call in a rapid burst
+ * actually runs (with its own arguments), after the window elapses.
+ *
+ * @param msecs Debounce delay in milliseconds, or `true` to debounce to the next animation frame (`requestAnimationFrame`) instead of a fixed delay. Defaults to `50`.
+ * @param keyFactory Computes the per-instance timer key from the method name and call arguments; override to scope debouncing per argument (e.g. debounce separately per id) instead of per method. Defaults to a single shared key per method.
+ * @returns A method decorator to apply to the instance method to debounce.
+ */
 export declare function Debounce(msecs?: true | number, keyFactory?: (key: String, ...args: any[]) => string): (target: any, key: string, descriptor?: PropertyDescriptor) => void;
 
+/**
+ * Recursively clones plain objects, arrays, `Date`s and `RegExp`s, preserving reference cycles/shared
+ * references within a single `clone` call (via an internal `WeakMap`). DOM `Element`s, `FileSystemHandle`s
+ * and `File`s are returned as-is (not cloned) - they aren't meaningfully deep-cloneable and are typically
+ * meant to be referenced, not duplicated.
+ */
 export declare class DeepCloner {
     private constructor();
+    /** Deep-clones `obj`; see {@link DeepCloner} for what gets cloned vs. passed through by reference. */
     static clone(obj: any): any;
     private _clone;
 }
@@ -396,22 +666,33 @@ export declare class DeepCloner {
  */
 export declare const DefaultComparer: PropertyComparer<any>;
 
+/** Framework-wide default settings. */
 export declare const Defaults: {
     USE_SHADOW_ROOT: boolean;
 };
 
+/**
+ * A `PromiseLike<T>` whose resolution is externalized: unlike a plain `Promise`, the executor isn't
+ * passed a callback up front - instead, `resolve`/`reject` are exposed for the caller to invoke later,
+ * via the {@link defer} static factory. Useful when the completion of an operation is driven by code
+ * that doesn't naturally live inside a `Promise` executor (e.g. event callbacks, decorator plumbing).
+ */
 export declare class DeferPromise<T> implements PromiseLike<T> {
     private promise;
     private deferred;
     constructor();
+    /** Standard `PromiseLike.then`, delegating to the underlying native `Promise`. */
     then<TResult1 = T, TResult2 = never>(onCompleted?: ((v: T) => TResult1 | PromiseLike<TResult1>), onFailed?: (v?: any) => TResult2 | PromiseLike<TResult2>): PromiseLike<TResult1 | TResult2>;
     /**
      * Occurs whenever the promise concludes (either after completion or error).
      * @param {Function } callback
      */
     finally(callback: (v?: T | any) => void | PromiseLike<void>): this;
+    /** Registers a fulfillment-only callback (fluent, chainable alternative to `then(callback)`). */
     success(callback: (v?: T) => T | PromiseLike<T>): this;
+    /** Registers a rejection-only callback (fluent, chainable alternative to `then(null, callback)`). */
     error(callback: (v?: any) => void | PromiseLike<void>): this;
+    /** Creates a new deferred promise and returns its controller: `{ resolve, reject, promise }`. */
     static defer<T>(): {
         resolve: (v?: T) => void | PromiseLike<void>;
         reject: (v?: any) => void | PromiseLike<void>;
@@ -424,6 +705,7 @@ declare enum DockMode {
     Bottom = "bottom"
 }
 
+/** Options accepted by the URL-based overload of {@link Utils.download}. */
 declare type DownloadOptions = {
     filename?: string;
     mime?: string;
@@ -442,10 +724,16 @@ declare enum DragDataMode {
     Copy = "copy"
 }
 
+/**
+ * Custom UI event dispatched throughout the drag & drop lifecycle (see {@link DragDropEventType}).
+ */
 declare class DragDropEvent extends CustomUIEvent<DragDropEventArgsClass | DragDropInitEventArgsClass> {
     constructor(type: DragDropEventType, args: DragDropEventArgsClass | DragDropInitEventArgsClass, eventInit?: EventInit, evt?: MouseEvent | TouchEvent);
 }
 
+/**
+ * Plain data shape backing the drag & drop event-args classes.
+ */
 declare type DragDropEventArgs = {
     element: HTMLElement | SVGElement;
     placeholder: HTMLElement | SVGElement;
@@ -458,6 +746,9 @@ declare type DragDropEventArgs = {
     target?: Element;
 };
 
+/**
+ * Base class shared by the drag & drop event-args classes; wraps a {@link DragDropEventArgs} builder and exposes its common, read-only facets.
+ */
 declare abstract class DragDropEventArgsBaseClass {
     private _builder;
     protected constructor(_builder: DragDropEventArgs);
@@ -473,12 +764,18 @@ declare abstract class DragDropEventArgsBaseClass {
     get delta(): Point;
 }
 
+/**
+ * Read-only event args dispatched with the drag/drop lifecycle events other than `draginit` (start, drag, drop, over, out, end).
+ */
 declare class DragDropEventArgsClass extends DragDropEventArgsBaseClass {
     private _placeholder;
     private _data;
     private constructor();
+    /** @readonly Gets the element used as a dragging placeholder. */
     get placeholder(): HTMLElement | SVGElement;
+    /** @readonly Gets the logical payload being dragged. */
     get data(): any;
+    /** Builds a new {@link DragDropEventArgsClass} out of a plain {@link DragDropEventArgs} builder. */
     static fromArgs(builder: DragDropEventArgs): DragDropEventArgsClass;
 }
 
@@ -499,10 +796,17 @@ declare enum DragDropEventType {
     End = "dragend"
 }
 
+/**
+ * Event args dispatched with the {@link DragDropEventType.Init} event, mutable so listeners can override
+ * the `placeholder` and `data` before the drag actually starts.
+ */
 declare class DragDropInitEventArgsClass extends DragDropEventArgsBaseClass {
     private constructor();
+    /** Gets or sets the element to be used as a dragging placeholder. */
     placeholder: HTMLElement | SVGElement;
+    /** Gets or sets the logical payload being dragged. */
     data: any;
+    /** Builds a new {@link DragDropInitEventArgsClass} out of a plain {@link DragDropEventArgs} builder. */
     static fromArgs(builder: DragDropEventArgs): DragDropInitEventArgsClass;
 }
 
@@ -525,7 +829,9 @@ declare interface DragDropper {
      * Element to be used as a dragging placeholder. If not null, will override the floater obtained via the `mode` property.
      */
     floater: Element;
+    /** Gets or sets the meaning of a drop action (e.g. insert as a child, or none). */
     dropBehavior: DropBehavior;
+    /** Gets or sets what happens when a dragged element is released outside of any valid drop target. */
     spillBehavior: DropTargetMissedBehavior;
 }
 
@@ -545,20 +851,32 @@ declare enum DropTargetMissedBehavior {
     None = "none"
 }
 
+/**
+ * A normalized-time easing function (`[0,1] -> [0,1]`, roughly) that also carries its CSS `cubic-bezier`/`linear` equivalent under the `css` property.
+ */
 declare type Easing = (any: any) => any & {
     css: string;
 };
 
+/**
+ * Collection of ready-made {@link Easing} functions, each paired with its CSS timing-function equivalent.
+ */
 declare const Easings: any;
 
+/** A pattern that can never match any string (`/a^/`); useful as a safe no-op default for optional matcher parameters. */
 export declare const EMPTY_MATCHER: RegExp;
 
+/** A pointer position expressed in the three coordinate systems normally exposed by mouse/touch events. */
 export declare interface EventCoordinates {
+    /** Position relative to the whole document, including any scrolled-away area. */
     readonly page: Point;
+    /** Position relative to the viewport. */
     readonly client: Point;
+    /** Position relative to the physical screen. */
     readonly screen: Point;
 }
 
+/** String tokens accepted by {@link CustomEventUtils.matchModifiers} to describe a keyboard/mouse modifier. */
 export declare enum EventKeyModifier {
     AltKey = "Alt",
     CtrlKey = "Ctrl",
@@ -566,9 +884,20 @@ export declare enum EventKeyModifier {
     MetaKey = "Cmd"
 }
 
+/** Snapshot of the keyboard-modifier state captured off an original native event; see {@link CustomEventUtils.getEventKeyModifiers}. */
 export declare interface EventKeyModifiers extends KeyEventLike {
 }
 
+/**
+ * A parsed, compiled binding expression (the content of a `{{ ... }}` attribute value). Parsing
+ * (see {@link parse}) rewrites special tokens found in the source text - `:host.`, `^item`/`^^item`/...,
+ * `^index`/`^^index`/..., `#id`, `::hostProp` - into references resolvable at evaluation time, and
+ * records each of them as a {@link PropertyDependency} so the owning element can be notified (via
+ * {@link PropertyChangeEvent}) and re-evaluate the expression whenever a dependency changes - this is
+ * what powers the two-way/live data binding wired up by the {@link CustomElement} decorator.
+ * Expressions with no dependencies are flagged `independent` (effectively a constant) and can be
+ * evaluated immediately without waiting for the DOM/scope to be ready.
+ */
 export declare class Expression {
     private _fnBody;
     private _voidBody;
@@ -577,47 +906,89 @@ export declare class Expression {
     private _args;
     private _dependencies;
     private _fn;
+    /** The resolved property dependencies (element + property + path) this expression re-evaluates on change. Empty for {@link independent} expressions. */
     get dependencies(): PropertyDependency[];
+    /** The compiled function body used by {@link evaluate}/{@link evaluateAsync} (a `return <expr>;` statement, guarded by a try/catch). */
     get functionBody(): string;
+    /** The compiled function body used by {@link evaluatePlus} (a bare, non-`return`ing statement, guarded by a try/catch) - suited for expressions run for their side effects, e.g. `on-*` event handlers. */
     get voidBody(): string;
+    /**
+     * `true` when this expression couldn't be resolved against a scope yet (the element wasn't connected
+     * to a document/shadow-root at parse time) - a shared, inert placeholder singleton returned by
+     * {@link parse} in that case; evaluating it is a no-op. Callers should re-parse once the element is ready.
+     */
     get pending(): boolean;
+    /** `true` when the expression has no dependencies (a constant) and can be evaluated immediately, without a resolved scope. */
     get independent(): boolean;
+    /** Evaluates the expression and returns its result, swallowing any runtime error (returning `undefined`). */
     evaluate(): any;
+    /** Promise-wrapped variant of {@link evaluate} (resolves synchronously with the same result - kept for call-site uniformity with genuinely async evaluation paths). */
     evaluateAsync(): PromiseLike<any>;
+    /**
+     * Executes the expression for its side effects (using {@link voidBody}, so no value is returned),
+     * with extra named variables merged into scope alongside the expression's own dependencies -
+     * used to expose e.g. `$event` to `on-*` event handler expressions.
+     * @param args Extra name/value pairs made available to the expression, in addition to its resolved dependencies.
+     */
     evaluatePlus(args?: {
         [key: string]: any;
     }): any;
     private static _pendingExpression;
     private static _getPendingExpressionSingleton;
+    /**
+     * Parses a binding expression's source text (the bare content of a `{{ ... }}` attribute, without the
+     * delimiters - see {@link CustomElementUtils.extractBindingAttributeExpression}) into an {@link Expression},
+     * resolving its special tokens against `element`'s scope (see {@link CustomElementUtils.findScopeContext}).
+     * Throws if the expression matches the unsafe-code guard (`new`, `window.`, `document.`, `eval(`).
+     * @param expression Bare expression source text.
+     * @param element Element the expression is bound to; provides the scope special tokens (`:host.`, `#id`, `^item`, ...) resolve against.
+     * @returns A constant expression if it has no dependencies; a shared pending placeholder if `element` isn't attached to a scope yet; otherwise a fully resolved expression.
+     */
     static parse(expression: string, element: HTMLElement): Expression;
 }
 
+/** Describes an element capable of issuing an HTTP request and exposing its outcome (e.g. `PacemFetchElement`); dispatches {@link FetchResultEventName}/{@link FetchSuccessEventName}/{@link FetchErrorEventName} as appropriate and notifies property changes for `result`. */
 declare interface Fetcher extends NotifyPropertyChange {
+    /** Target URL of the request. */
     url: string;
+    /** HTTP method to use. */
     method: HttpMethod;
+    /** Query/body parameters, name/value pairs. */
     parameters: {
         [key: string]: string;
     };
+    /** Extra request headers, name/value pairs. */
     headers: {
         [key: string]: string;
     };
+    /** The (parsed) outcome of the last successful fetch, if any. */
     result: any;
+    /** Issues the request. @returns A promise resolving with the raw `Response`. */
     fetch: () => PromiseLike<GlobalResponse>;
 }
 
+/** Static helpers for working with fetch `Response`s. */
 declare class Fetcher {
+    /** Tests whether a response carries no body (HTTP 204, or an explicit `Content-Length: 0`). */
     static isEmpty(r: GlobalResponse): boolean;
 }
 
+/** Event name dispatched when a {@link Fetcher}'s request fails. */
 declare const FetchErrorEventName = "error";
 
+/** Event name dispatched with the raw fetch result payload; see {@link Fetcher.result}. */
 declare const FetchResultEventName = "fetchresult";
 
+/** Event name dispatched when a {@link Fetcher}'s request completes successfully. */
 declare const FetchSuccessEventName = "success";
 
 declare type GlobalResponse = Response;
 
-/** @deprecated */
+/**
+ * Legacy `XMLHttpRequest`-based HTTP client, superseded by the standard `fetch` API and {@link Fetcher}.
+ * Kept for backward compatibility.
+ * @deprecated
+ */
 declare class Http {
     constructor();
     /** Gets or sets the Bearer authorization token. */
@@ -646,6 +1017,7 @@ declare class Http {
     }): DeferPromise<Response_2>;
 }
 
+/** HTTP verbs accepted by {@link Fetcher.method} / {@link Http}. */
 declare enum HttpMethod {
     Get = "GET",
     Post = "POST",
@@ -658,15 +1030,21 @@ declare enum HttpMethod {
     Trace = "TRACE"
 }
 
+/** Payload carried by a {@link CurrentIndexChangeEvent}. */
 export declare type IndexChangeEventArgs = {
+    /** The newly selected index. */
     currentIndex: number;
+    /** The previously selected index. */
     previousIndex: number;
 };
 
+/** Key used to attach, on an element instance, the list of attribute names currently holding a pending (not-yet-evaluable) binding expression. */
 export declare const INSTANCE_BINDINGS_VAR = "pacem:custom-element:bindings";
 
+/** Key used to attach, on a templated node, a reference to the custom element instance ("host") whose template produced it — used to resolve binding expression scope. */
 export declare const INSTANCE_HOST_VAR = "pacem:custom-element:host";
 
+/** Key used to attach, on an element instance, its binding-expression evaluation scope object. */
 export declare const INSTANCE_SCOPE_VAR = "pacem:custom-element:scope";
 
 declare function isItemsContainer(object: any): object is ItemsContainer<any>;
@@ -688,9 +1066,13 @@ declare class ItemRegisterEvent<TItem extends PacemItemElement> extends CustomTy
 
 declare const ItemRegisterEventName = "itemregister";
 
+/** An element that holds and tracks a collection of `TItem` items (e.g. a set of child controls), notifying property changes as they're registered/unregistered. */
 export declare interface ItemsContainer<TItem> extends NotifyPropertyChange {
+    /** The currently registered items. */
     items: TItem[];
+    /** Adds `item` to the collection. @returns `true` if the item was newly registered. */
     register(item: TItem): boolean;
+    /** Removes `item` from the collection. @returns `true` if the item was found and removed. */
     unregister(item: TItem): boolean;
 }
 
@@ -700,14 +1082,30 @@ declare class ItemUnregisterEvent<TItem extends PacemItemElement> extends Custom
 
 declare const ItemUnregisterEventName = "itemunregister";
 
+/** An {@link ItemsContainer} that additionally tracks a "current" position (`index`) within its items (e.g. a carousel or tab strip); see {@link CurrentIndexChangeEvent}. */
 export declare interface Iterative<TItem> extends ItemsContainer<TItem> {
+    /** The currently selected/active item's position within {@link ItemsContainer.items}. */
     index: number;
 }
 
+/**
+ * A `JSON.stringify`/`JSON.parse` superset able to round-trip values plain JSON can't represent: circular/
+ * shared object references (`$#ref_N` markers), `RegExp` instances, DOM `Element`s (serialized by `id`
+ * and revived via `document.getElementById`, so they must have one), and - depending on
+ * {@link JsonSerializationOptions.functions} - functions themselves. The source object is deep-cloned
+ * first (via {@link DeepCloner}) so serialization never mutates the input.
+ */
 export declare class Json {
     private _options?;
     private constructor();
+    /**
+     * Serializes `obj` to a JSON string, extended to support circular/shared references, `RegExp`s,
+     * `Element`s (by `id`) and, per `options`, functions.
+     * @param obj Value to serialize.
+     * @param options Controls how function-valued properties are handled.
+     */
     static serialize(obj: any, options?: JsonSerializationOptions): string;
+    /** Deserializes a string produced by {@link serialize}, restoring references, `RegExp`s, `Element`s and functions. */
     static deserialize(json: string): any;
     private _serialize;
     private _deserialize;
@@ -725,21 +1123,32 @@ export declare enum JsonFunctionConversion {
     Plain = "plain"
 }
 
+/** Options accepted by {@link Json.serialize}. */
 export declare interface JsonSerializationOptions {
+    /** How to handle function-valued properties encountered while serializing; see {@link JsonFunctionConversion}. Defaults to {@link JsonFunctionConversion.Ignore}. */
     functions?: JsonFunctionConversion;
 }
 
 declare const KeyboardShortcutExecuteEventName = "execute";
 
+/** Minimal shape of the keyboard-modifier flags found on keyboard/mouse/touch events. */
 export declare interface KeyEventLike {
     readonly altKey: boolean;
     readonly ctrlKey: boolean;
     readonly shiftKey: boolean;
     readonly metaKey: boolean;
+    /** Key code (`KeyboardEvent.which`) or, for mouse events, the pressed button (`MouseEvent.button`). */
     readonly which?: number;
 }
 
+/** Minimal logging sink interface; assigned to an element's `logger` property (see {@link PacemEventTarget.logger}) to receive its diagnostic output. */
 declare interface Logger {
+    /**
+     * Records a log entry.
+     * @param level Severity of the entry.
+     * @param message Text content of the entry.
+     * @param category Optional grouping/source label (e.g. the emitting element's tag/id).
+     */
     log(level: LogLevel, message: string, category?: string): any;
 }
 
@@ -750,12 +1159,19 @@ export declare namespace Logging {
     }
 }
 
+/** Severity levels accepted by {@link Logger.log}, and used by {@link PacemEventTarget.log}. */
 declare enum LogLevel {
+    /** Fine-grained diagnostic detail. */
     Trace = "trace",
+    /** Development-time diagnostic detail. */
     Debug = "debug",
+    /** Recoverable but noteworthy condition. */
     Warn = "warn",
+    /** Unrecoverable or unexpected failure. */
     Error = "error",
+    /** General informational message. */
     Info = "info",
+    /** Generic/default-severity message. */
     Log = "log"
 }
 
@@ -774,25 +1190,33 @@ export declare namespace Net {
     }
 }
 
+/** Marker interface for an `EventTarget` capable of dispatching {@link PropertyChangeEvent}s (i.e. hosts one or more `@Watch`-decorated properties). */
 export declare interface NotifyPropertyChange extends EventTarget {
 }
 
+/** Implemented by an element that augments a {@link Fetcher} with OAuth-flavored credentials/headers to attach to its requests. */
 declare interface OAuthFetchable {
+    /** The {@link Fetcher} this OAuth configuration applies to, if resolved. */
     readonly fetcher?: Fetcher;
+    /** `RequestInit.credentials` mode to use for the fetch (e.g. `'include'`). */
     fetchCredentials: RequestCredentials;
+    /** Extra headers (typically an `Authorization` bearer token) to merge into the request. */
     fetchHeaders: {
         [key: string]: string;
     };
 }
 
+/** Implemented by elements that need to react to the standard Custom Elements `adoptedCallback` lifecycle hook. */
 export declare interface OnAdopted {
     adoptedCallback(): void;
 }
 
+/** Implemented by elements that need to react to the standard Custom Elements `attributeChangedCallback` lifecycle hook. */
 export declare interface OnAttributeChanged {
     attributeChangedCallback(attrName?: string, oldVal?: string, newVal?: string): void;
 }
 
+/** Implemented by elements that need to react to the standard Custom Elements `connectedCallback` lifecycle hook. */
 export declare interface OnConnected {
     connectedCallback(): void;
 }
@@ -801,6 +1225,7 @@ declare interface OnDestroy {
     destroyCallback(): void;
 }
 
+/** Implemented by elements that need to react to the standard Custom Elements `disconnectedCallback` lifecycle hook. */
 export declare interface OnDisconnected {
     disconnectedCallback(): void;
 }
@@ -809,10 +1234,12 @@ declare interface OnInitialize {
     initializeCallback(): void;
 }
 
+/** Implemented by elements that need to react whenever one of their `@Watch`-decorated properties changes value. */
 export declare interface OnPropertyChanged {
     propertyChangedCallback(name?: string, oldVal?: any, newVal?: any, firstChange?: boolean): void;
 }
 
+/** Implemented by elements that need to react once their template content (and that of their descendants) has been fully rendered and activated; see the `viewActivatedCallback` hook wired up by the {@link CustomElement} decorator. */
 export declare interface OnViewActivated {
     viewActivatedCallback(): void;
 }
@@ -820,6 +1247,7 @@ export declare interface OnViewActivated {
 /** the overall customelement prefix */
 export declare const P: any;
 
+/** Base class for pluggable adapters that drive the focus/navigation behavior of a {@link PacemIterativeElement}. */
 declare abstract class PacemAdapter<TIterative extends Iterative<TItem>, TItem> extends PacemElement implements OnInitialize, OnDestroy {
     private _element;
     /** Gets the adapted element. */
@@ -869,6 +1297,10 @@ declare abstract class PacemAdapter<TIterative extends Iterative<TItem>, TItem>
      * @param ndx index to be checked
      */
     isNext(ndx: number): boolean;
+    /**
+     * Sets the master's index to the closest available item to the provided one.
+     * @param ndx Desired index
+     */
     select(ndx: number): void;
     /**
      * Sets the new iterative's index to the closest available previous item.
@@ -884,25 +1316,44 @@ declare abstract class PacemAdapter<TIterative extends Iterative<TItem>, TItem>
     next(loop: boolean): void;
 }
 
+/** Removes itself from the DOM as soon as it gets connected; handy to strip out placeholder markup at runtime. */
 declare class PacemAnnihilatorElement extends HTMLElement {
     constructor();
     connectedCallback(): void;
 }
 
+/** Warns the user (native `beforeunload` prompt or router-driven confirm dialog) before leaving the page. */
 declare class PacemBeforeunloadElement extends PacemEventTarget {
+    /** Gets or sets the confirmation message to display. */
     message: string;
+    /** Gets or sets whether the warning is currently armed. */
     active: boolean;
     private _unloadingHandler;
     viewActivatedCallback(): void;
     disconnectedCallback(): void;
 }
 
+/**
+ * Base class for the "behavior" custom elements (drag & drop, swipe, rotate, rescale, ...) that attach
+ * gesture-driven functionality to a set of registered elements without rendering anything of their own.
+ */
 declare abstract class PacemBehavior extends PacemEventTarget {
     #private;
+    /** Hooks up the behavior-specific event listeners/markup on a newly registered element. */
     protected abstract decorate(element: Element): any;
+    /** Tears down whatever {@link decorate} set up on a previously registered element. */
     protected abstract undecorate(element: Element): any;
+    /**
+     * Registers an element with this behavior, decorating it if it wasn't already registered.
+     * @param element Element to register.
+     */
     register(element: Element): void;
+    /**
+     * Unregisters a previously registered element, undecorating it.
+     * @param element Element to unregister.
+     */
     unregister(element: Element): void;
+    /** @readonly Determines whether the given element is currently registered with this behavior. */
     protected has(element: Element): boolean;
 }
 
@@ -911,16 +1362,24 @@ declare class PacemBodyProxyElement extends PacemTransferProxyElement {
     protected get proxy(): HTMLElement;
 }
 
+/** Wraps a {@link BroadcastChannel}, sending/receiving messages to/from other same-origin browsing contexts. */
 declare class PacemBroadcastChannelProxyElement extends PacemEventTarget {
     #private;
+    /** Gets or sets the message to be sent through the channel. */
     message: any;
-    /** @readonly */
+    /** @readonly Gets the last message received through the channel. */
     result: any;
+    /** Gets or sets the name of the channel to open. */
     channelName: string;
+    /** Gets or sets whether to automatically send `message` as soon as it changes (default `true`). */
     autosend: boolean;
     viewActivatedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     disconnectedCallback(): void;
+    /**
+     * Posts a message through the channel.
+     * @param message Message to send; defaults to the current `message` property
+     */
     send(message?: any): void;
     private _messageHandler;
     private _errorHandler;
@@ -928,19 +1387,26 @@ declare class PacemBroadcastChannelProxyElement extends PacemEventTarget {
     private _disposeChannel;
 }
 
+/** Detects the name and version of the current (or a provided) browser user agent. */
 declare class PacemBrowserDetectElement extends PacemEventTarget {
     #private;
     viewActivatedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Gets or sets the user agent string to detect; defaults to `navigator.userAgent`. */
     userAgent: string;
+    /** @readonly Gets the detected browser name. */
     get browser(): string;
+    /** @readonly Gets the detected browser version. */
     get version(): string;
     private _detect;
 }
 
+/** Animates a CSS color `target[property]` from `from` to `to` (interpolated in HSLA space) over `duration`. */
 declare class PacemColorAnimationElement extends TweenAnimationElement<string> {
     #private;
+    /** Gets or sets the starting color (any CSS-parsable color string). */
     from: string;
+    /** Gets or sets the ending color (any CSS-parsable color string). */
     to: string;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     viewActivatedCallback(): void;
@@ -949,11 +1415,14 @@ declare class PacemColorAnimationElement extends TweenAnimationElement<string> {
     private _precomputeTo;
     private _precomputeColor;
     private _parseColor;
+    /** @inheritdoc */
     protected tweenInterpolationCallback(time: number, progress: number): string;
 }
 
+/** Base class for elements whose (sanitized) inner content is driven by a `content` property, restoring the original markup on disconnect. */
 declare abstract class PacemContentElement extends PacemElement {
     protected abstract sanitize(html: string | Node): string | Node;
+    /** Gets or sets the (HTML string or Node) content to render, passed through `sanitize` first. */
     content: string | Node;
     private _original;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
@@ -983,10 +1452,13 @@ declare abstract class PacemCrossItemsContainerElement<TItem extends PacemItemEl
     unregister(item: TItem): boolean;
 }
 
+/** Holds an arbitrary data model, optionally persisting it to local storage and debouncing/throttling change notifications. */
 declare class PacemDataElement extends PacemEventTarget {
     private storage;
     constructor(storage?: Storage_2);
+    /** Gets or sets the data model held by this element. */
     model: any;
+    /** Gets or sets the storage key under which `model` is persisted. */
     persistAs: string;
     /** Debounces the model change */
     debounce: number;
@@ -1015,14 +1487,20 @@ declare class PacemDockElement extends PacemEventTarget {
 }
 
 /**
- * Pacem Drag & Drop element adapter.
+ * Pacem Drag & Drop element adapter: implements {@link DragDropper} on top of {@link PacemBehavior} to make
+ * registered elements draggable and, optionally, sortable/droppable onto {@link dropTargets}.
  */
 declare class PacemDragDropElement extends PacemBehavior implements DragDropper {
     private _startHandler;
+    /** Wires up the `mousedown`/`touchstart` listeners that arm the drag gesture on the given element. */
     protected decorate(element: Element): void;
+    /** Removes the listeners set up by {@link decorate}. */
     protected undecorate(element: Element): void;
+    /** Registers a listener for a {@link DragDropEventType} lifecycle event. */
     addEventListener(type: DragDropEventType, listener: (evt: DragDropEvent) => void, useCapture?: boolean): void;
+    /** Unregisters a listener previously added for a {@link DragDropEventType} lifecycle event. */
     removeEventListener(type: DragDropEventType, listener: (evt: DragDropEvent) => void, useCapture?: boolean): void;
+    /** Dispatches a {@link DragDropEvent}, clearing internal per-element bookkeeping once the drag ends. */
     dispatchEvent(evt: DragDropEvent): boolean;
     /** Gets or sets the amount of milliseconds to wait, while pressing on the draggable object, until the object itself must be considered "locked to drag". */
     lockTimeout: number;
@@ -1040,6 +1518,7 @@ declare class PacemDragDropElement extends PacemBehavior implements DragDropper
     handleSelector: string;
 }
 
+/** Common base class for Pacem custom elements: adds ARIA support, CSS class/part/style bags, visibility, tab order and behaviors. */
 declare class PacemElement extends PacemEventTarget implements Wai {
     #private;
     constructor(role?: string, aria?: {
@@ -1053,19 +1532,27 @@ declare class PacemElement extends PacemEventTarget implements Wai {
     disconnectedCallback(): void;
     private _tabIndex;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Gets or sets the CSS classes to toggle on this element, either as a string array or a `{ [className]: boolean }` map. */
     cssClass: {
         [key: string]: boolean;
     } | string[];
+    /** Gets or sets the CSS shadow parts (`::part()`) to toggle on this element, either as a string array or a `{ [partName]: boolean }` map. */
     cssPart: {
         [key: string]: boolean;
     } | string[];
+    /** Gets or sets inline CSS custom properties/values to apply to this element's style. */
     css: {
         [key: string]: string;
     };
+    /** Gets or sets whether the element is hidden (animated out, then marked `hidden` and `aria-hidden`). */
     hide: boolean;
+    /** Gets or sets the tooltip text, mapped to both `title` and `aria-label`. */
     tooltip: string;
+    /** Gets or sets the tab order; mirrors `tabIndex` while the element is enabled. */
     tabOrder: number;
+    /** Gets or sets the culture (mapped to the `lang` attribute); assigning it also refreshes data bindings. */
     culture: string;
+    /** Gets or sets the list of behaviors to attach to this element. */
     behaviors: PacemBehavior[];
 }
 
@@ -1076,9 +1563,13 @@ declare class PacemElementProxyElement extends PacemTransferProxyElement {
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** Listens for an arbitrary DOM event on a `target` element (or `window`) and re-dispatches it as its own `emit` event. */
 declare class PacemEventProxyElement extends PacemEventTarget {
+    /** Gets or sets the element (or `window`, via the special `"$window"` value) to listen on. */
     target: HTMLElement | Window;
+    /** Gets or sets the name of the DOM event to listen for. */
     event: string;
+    /** Gets or sets whether to listen in the capture phase. */
     capture: boolean;
     viewActivatedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
@@ -1088,6 +1579,16 @@ declare class PacemEventProxyElement extends PacemEventTarget {
     private _emitHandler;
 }
 
+/**
+ * Base class for (almost) every Pacem custom element. Extends `HTMLElement` with the framework's
+ * common lifecycle/event plumbing: `on-{event-type}` attribute handlers (see {@link emit}), a
+ * {@link disabled} property that suppresses both outgoing (`dispatchEvent`) and incoming
+ * (`emitHandler`) events, an optional {@link logger} sink, and an {@link isReady} flag toggled once
+ * `viewActivatedCallback` has fired (see the {@link CustomElement} decorator for when that happens).
+ * Concrete elements are expected to be decorated with `@CustomElement` and typically override
+ * `propertyChangedCallback`/`viewActivatedCallback`/`connectedCallback`/`disconnectedCallback`,
+ * calling `super.xxxCallback()` first/last as documented on each.
+ */
 export declare abstract class PacemEventTarget extends HTMLElement implements NotifyPropertyChange, OnPropertyChanged, OnConnected, OnViewActivated, OnDisconnected {
     constructor();
     /**
@@ -1096,6 +1597,12 @@ export declare abstract class PacemEventTarget extends HTMLElement implements No
      */
     protected emit(evt: Event): void;
     private _emitCore;
+    /**
+     * Emits (see {@link emit}) either an existing `Event`, or a new one synthesized from a `type` name
+     * and optional `detail` payload (as a `CustomEvent` when `detail` is provided, a plain `Event` otherwise).
+     * @param evt The event to emit, or the type name of a new event to synthesize.
+     * @param detail Optional payload for a synthesized `CustomEvent`; ignored when `evt` is already an `Event`.
+     */
     handle(evt: Event): any;
     handle(type: string, detail?: any): any;
     private _isReady;
@@ -1118,7 +1625,9 @@ export declare abstract class PacemEventTarget extends HTMLElement implements No
      */
     dispatchEvent(evt: Event): boolean;
     protected emitHandler: (evt: Event) => void;
+    /** Gets or sets whether the element is disabled: while `true`, {@link dispatchEvent} is a no-op and {@link emitHandler} ignores incoming events. Reflected back onto the `disabled` attribute. */
     disabled: boolean;
+    /** Gets or sets the {@link Logger} sink (resolved from a `logger="#elementId"` selector attribute) that {@link log} writes to, if any. */
     logger: Logger;
     /**
      * Logs a message if a logger is available.
@@ -1131,28 +1640,42 @@ export declare abstract class PacemEventTarget extends HTMLElement implements No
     protected refreshBindings(): void;
 }
 
+/** Declarative wrapper around the `fetch()` API, debouncing/aborting requests as its properties change and exposing the parsed `result`. */
 declare class PacemFetchElement extends PacemEventTarget implements Fetcher {
     #private;
+    /** Gets or sets the request URL, optionally templated (e.g. `/api/{id}`) against `parameters`. */
     url: string;
+    /** Gets or sets the HTTP method (default `GET`). */
     method: HttpMethod;
+    /** Gets or sets the request parameters: appended as querystring on `GET`, or serialized as body otherwise. */
     parameters: {
         [key: string]: string;
     };
+    /** Gets or sets additional request headers. */
     headers: {
         [key: string]: string;
     };
+    /** Gets or sets the request's `credentials` mode. */
     credentials: 'omit' | 'same-origin' | 'include';
+    /** Gets or sets the request's `mode`. */
     mode: 'cors' | 'no-cors' | 'navigate' | 'same-origin';
+    /** Gets or sets the request's `cache` mode. */
     cache: RequestCache;
+    /** @readonly Gets whether a request is currently in flight. */
     fetching: boolean;
     /** Gets or sets whether to trigger a fetch whenever a significant property has changed (default: true). */
     autofetch: boolean;
+    /** Gets or sets how to parse the response body (`object`, `text`, `blob` or `image`; default `object`). */
     as: 'object' | 'text' | 'blob' | 'image';
+    /** Gets or sets the request payload encoding (`json` or `raw`, i.e. urlencoded; default `json`). */
     type: 'json' | 'raw';
+    /** Gets or sets the debounce delay (in milliseconds) applied before auto-triggered fetches (default `100`). */
     debounce: number;
+    /** Gets or sets whether to throttle (rather than debounce) auto-triggered fetches. */
     throttle: boolean;
     /** Gets or sets whether to compare parameter and header single values prior to trigger a new fetch execution (default false). */
     diffByValues: boolean;
+    /** @readonly Gets the parsed result of the last successful fetch. */
     result: any;
     private _handle;
     viewActivatedCallback(): void;
@@ -1164,37 +1687,49 @@ declare class PacemFetchElement extends PacemEventTarget implements Fetcher {
     private _acceptFetchResult;
 }
 
+/** Keeps track of an undo/redo-capable history of an arbitrary state. */
 declare class PacemHistoryElement extends PacemEventTarget {
     #private;
+    /** Gets or sets the current state; assigning a new value pushes it onto the history stack. */
     state: any;
+    /** Gets or sets the maximum number of states retained in the history stack. */
     maxlength: number;
-    /** @readonly*/
+    /** @readonly Gets whether `undo()` can currently be invoked. */
     canUndo: boolean;
-    /** @readonly*/
+    /** @readonly Gets whether `redo()` can currently be invoked. */
     canRedo: boolean;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     viewActivatedCallback(): void;
     private _handleStateChange;
+    /** Moves the state forward one step, if `canRedo` is `true`. */
     redo(): void;
+    /** Clears the history stack, keeping only the current state. */
     reset(): void;
+    /** Moves the state back one step, if `canUndo` is `true`. */
     undo(): void;
     private _synchronize;
 }
 
+/** Sets (or removes) an attribute on the document's root `<html>` element. */
 declare class PacemHtmlProxyElement extends PacemEventTarget {
+    /** Gets or sets the name of the `<html>` attribute to manage. */
     attr: string;
+    /** Gets or sets the value to assign to the attribute; an empty value removes it. */
     value: string;
     private _html;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     private _update;
 }
 
+/** Conditionally shows or clears its own inner content, restoring the original markup whenever `match` becomes truthy again. */
 declare class PacemIfElement extends HTMLElement {
     #private;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Gets or sets whether the original content is shown (`true`) or cleared (`false`). */
     match: boolean;
 }
 
+/** Base class for elements that register themselves against an ancestor {@link PacemItemsContainerElement}. */
 declare abstract class PacemItemElement extends PacemElement {
     private _container;
     protected get container(): ItemsContainer<any>;
@@ -1204,6 +1739,7 @@ declare abstract class PacemItemElement extends PacemElement {
     disconnectedCallback(): void;
 }
 
+/** Base class for container elements holding a registry of {@link PacemItemElement} children. */
 declare abstract class PacemItemsContainerElement<TItem extends PacemItemElement> extends PacemElement implements ItemsContainer<TItem> {
     constructor(role?: string, aria?: {
         [name: string]: string;
@@ -1223,14 +1759,18 @@ declare abstract class PacemItemsContainerElement<TItem extends PacemItemElement
     unregister(item: TItem): boolean;
 }
 
+/** Base class for items belonging to a {@link PacemIterativeElement}, forwarding their property changes to the master's `adapter`. */
 declare abstract class PacemIterableElement extends PacemItemElement {
     /** @overrides */
     protected findContainer(): any;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** Base class for container elements whose items are driven by a pluggable {@link PacemAdapter}, tracking a `current` `index`. */
 declare abstract class PacemIterativeElement<TItem extends PacemIterableElement> extends PacemItemsContainerElement<TItem> implements Iterative<TItem> {
+    /** Gets or sets the adapter that drives the behavior/UI of this iterative element. */
     adapter: PacemAdapter<PacemIterativeElement<TItem>, TItem>;
+    /** Gets or sets the index of the currently focused/selected item. */
     index: number;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     viewActivatedCallback(): void;
@@ -1238,9 +1778,12 @@ declare abstract class PacemIterativeElement<TItem extends PacemIterableElement>
     disconnectedCallback(): void;
 }
 
+/** Sets (or removes) an attribute on the closest ancestor shell element, e.g. to drive layout-wide CSS state. */
 declare class PacemLayoutProxyElement extends PacemEventTarget {
     #private;
+    /** Gets or sets the name of the shell attribute to manage. */
     attr: string;
+    /** Gets or sets the value to assign to the attribute; `"false"` removes it, `"true"` sets it empty. */
     value: string;
     connectedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
@@ -1248,22 +1791,32 @@ declare class PacemLayoutProxyElement extends PacemEventTarget {
     private _update;
 }
 
+/** Creates, updates or removes a `<meta>` element in the document `<head>`, keyed by either `name` or `itemprop`. */
 declare class PacemMetaProxyElement extends PacemEventTarget {
+    /** Gets or sets the `name` attribute used to look up the target `<meta>` element. */
     name: string;
+    /** Gets or sets the `itemprop` attribute used to look up the target `<meta>` element (used when `name` is not set). */
     itemprop: string;
+    /** Gets or sets the `content` attribute value; an empty value removes the element. */
     content: string;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     viewActivatedCallback(): void;
     private _update;
 }
 
+/** Animates a numeric `target[property]` from `from` to `to` over `duration`. */
 declare class PacemNumberAnimationElement extends TweenAnimationElement<number> {
+    /** Gets or sets the starting value. */
     from: number;
+    /** Gets or sets the ending value. */
     to: number;
+    /** @inheritdoc */
     protected tweenInterpolationCallback(time: number, progress: number): number;
 }
 
+/** Tracks the browser's network connectivity (`navigator.onLine`), updating `online` on `online`/`offline` events. */
 declare class PacemOnlineStatusElement extends PacemEventTarget {
+    /** @readonly Gets whether the browser currently reports itself as online. */
     online: boolean;
     connectedCallback(): void;
     viewActivatedCallback(): void;
@@ -1271,16 +1824,23 @@ declare class PacemOnlineStatusElement extends PacemEventTarget {
     private _onlineHandler;
 }
 
+/** Plain generic-purpose container element, useful as a databinding/behaviors host wherever a `<div>` would do. */
 declare class PacemPanelElement extends PacemSafeContentElement {
 }
 
+/** Animates a {@link Point} `target[property]` from `from` to `to` over `duration`. */
 declare class PacemPointAnimationElement extends TweenAnimationElement<Point> {
+    /** Gets or sets the starting point. */
     from: Point;
+    /** Gets or sets the ending point. */
     to: Point;
+    /** @inheritdoc */
     protected tweenInterpolationCallback(time: number, progress: number): Point;
 }
 
 /**
+ * Repeats its `<template>` content once per `datasource` item, keeping the rendered items in sync as the datasource changes.
+ * @example
  * <pacem-repeater datasource="[{id:'first', items:['a','b','c']}, ...]">
  * <ol>
  *    <li>
@@ -1296,15 +1856,18 @@ declare class PacemPointAnimationElement extends TweenAnimationElement<Point> {
  * </pacem-repeater>
  */
 declare class PacemRepeaterElement extends PacemEventTarget implements Repeater {
+    /** Gets or sets the collection of items to render, one per `<template>` instance. */
     datasource: any[];
     private _childItems;
     private _itemTemplate;
     private _childTemplatePlaceholder;
     private _fragment;
+    /** Removes the rendered item at the given index. */
     removeItem(index: number): void;
     private _setItem;
     private _removeItems;
     private _setupItem;
+    /** Forces a full re-render of the items against the current `datasource`. */
     databind(): void;
     private _databind;
     private _onCommand;
@@ -1315,14 +1878,26 @@ declare class PacemRepeaterElement extends PacemEventTarget implements Repeater
     propertyChangedCallback(name: string, old: any, val: any, first: boolean): void;
 }
 
+/**
+ * Pacem Rescale element adapter: implements {@link Rescaler} on top of {@link PacemBehavior}, decorating
+ * registered elements with draggable resize handles (see {@link RescaleHandle}).
+ */
 declare class PacemRescaleElement extends PacemBehavior implements Rescaler {
+    /** Adds the resize-handle frame (see {@link RescaleHandle}) around the given element. */
     protected decorate(element: Element): void;
+    /** Removes the resize-handle frame set up by {@link decorate}. */
     protected undecorate(element: Element): void;
+    /** Gets or sets the resize handles enabled on the registered elements. */
     handles: RescaleHandle[];
+    /** Gets or sets the minimum allowed width, in pixels. */
     minWidth: number;
+    /** Gets or sets the maximum allowed width, in pixels. */
     maxWidth: number;
+    /** Gets or sets the minimum allowed height, in pixels. */
     minHeight: number;
+    /** Gets or sets the maximum allowed height, in pixels. */
     maxHeight: number;
+    /** Gets or sets whether the width/height ratio must be preserved while resizing. */
     keepProportions: boolean;
     viewActivatedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
@@ -1333,8 +1908,11 @@ declare class PacemRescaleElement extends PacemBehavior implements Rescaler {
     private _startHandler;
 }
 
+/** Observes size (and, optionally, position) changes of itself or a `target` element, firing a `resize` event accordingly. */
 declare class PacemResizeElement extends PacemEventTarget {
+    /** Gets or sets the element to observe; defaults to this element itself. */
     target: Element;
+    /** Gets or sets whether to also track position changes via a per-frame poll (costlier than the native `ResizeObserver`-only path). */
     watchPosition: boolean;
     private get _target();
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
@@ -1350,30 +1928,56 @@ declare class PacemResizeElement extends PacemEventTarget {
     private _checkSizeHandler;
     private _assignSizeDebounced;
     private _checkSize;
+    /** @readonly Gets the last measured size (and position, if `watchPosition` is set) of the observed target. */
     get currentSize(): ResizeEventArgs;
     private _dispatchResize;
     connectedCallback(): void;
     disconnectedCallback(): void;
 }
 
+/**
+ * Pacem Rotate element adapter: implements {@link Rotator} on top of {@link PacemBehavior} to make
+ * registered elements rotatable around a pivot point via mouse/touch drag.
+ */
 declare class PacemRotateElement extends PacemBehavior implements Rotator {
+    /** Wires up the `mousedown`/`touchstart` listeners that arm the rotate gesture on the given element. */
     protected decorate(element: Element): void;
+    /** Removes the listeners set up by {@link decorate}. */
     protected undecorate(element: Element): void;
+    /** Gets or sets the step constrained amount, in radians; when greater than zero, rotation snaps to multiples of it. */
     step: number;
+    /** Gets or sets the minimum allowed rotation, in radians. */
     minRotation: number;
+    /** Gets or sets the maximum allowed rotation, in radians. */
     maxRotation: number;
+    /** Gets or sets the pivot point the element rotates around; defaults to the element's own center. */
     center: Point;
     private _startHandler;
 }
 
+/** Client-side router: parses/generates paths against a template and drives the browser History API. */
 declare class PacemRouterElement extends PacemEventTarget {
     #private;
+    /** Gets or sets the route template, e.g. `/{controller}/{action}/{id?}`. */
     template: string;
+    /** Gets or sets the current parsed state, derived from `path` against `template`. */
     state: RouterState;
+    /** Gets or sets the current path; assigning a new value triggers a `navigate`. */
     path: string;
+    /** Whether to restore the scroll position of a page visited via the back/forward buttons, and scroll newly-visited pages to top. Default `true`; set to `false` to fall back to the browser's own (native) scroll restoration. */
+    scrollRestoration: boolean;
+    /**
+     * Merges the provided partial state into the current one and returns the resulting parsed {@link RouterState}, without navigating.
+     * @param state Piece of new state to be merged
+     */
     parseState(state?: {
         [key: string]: string;
     }): RouterState;
+    /**
+     * Navigates to the provided path or partial state, pushing (or replacing) a new browser history entry.
+     * @param path Absolute/relative path, or a partial state object to be merged into the current one
+     * @param title Optional document title to set upon navigation
+     */
     navigate(path: string, title?: string): any;
     navigate(state: {
         [key: string]: string;
@@ -1382,6 +1986,7 @@ declare class PacemRouterElement extends PacemEventTarget {
     connectedCallback(): void;
     viewActivatedCallback(): void;
     disconnectedCallback(): void;
+    private _onScroll;
     private _onPopState;
     /**
      * Merged to provided state into the current one and returns the resulting path (including current querystring and hash).
@@ -1393,6 +1998,7 @@ declare class PacemRouterElement extends PacemEventTarget {
     private _parseState;
 }
 
+/** {@link PacemContentElement} variant that strips out `<script>` blocks (and, for `Node` content, `<script>` elements) before rendering `content`. */
 declare class PacemSafeContentElement extends PacemContentElement {
     private _sanitizeLegacy;
     protected sanitize(html: string | Node): string | Node;
@@ -1411,19 +2017,30 @@ declare class PacemScrollAwareElement extends PacemEventTarget {
     };
 }
 
+/** Registers a service worker and manages its (optional) Push API subscription. */
 declare class PacemServiceWorkerProxyElement extends PacemEventTarget {
-    /** @readonly */
+    /** @readonly Gets the active service worker registration, once available. */
     registration: ServiceWorkerRegistration;
-    /** @readonly */
+    /** @readonly Gets the current push subscription, once available. */
     pushSubscription: PushSubscription;
+    /** Gets or sets the URL of the service worker script to register. */
     src: string;
+    /** Gets or sets the VAPID public key (base64url) used when subscribing to push notifications. */
     publicKey: string;
     viewActivatedCallback(): void;
     disconnectedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     private _tryUnregister;
     private _tryRegister;
+    /**
+     * Unsubscribes from push notifications.
+     * @param subscription Subscription to cancel; defaults to the current `pushSubscription`
+     */
     unsubscribe(subscription?: PushSubscription): Promise<boolean>;
+    /**
+     * Subscribes to push notifications through the registered service worker.
+     * @param publicKey VAPID public key (base64url or raw bytes); defaults to `publicKey`
+     */
     subscribe(publicKey?: string | Uint8Array<ArrayBuffer>): Promise<PushSubscription>;
 }
 
@@ -1432,8 +2049,11 @@ declare class PacemShellProxyElement extends PacemTransferProxyElement {
     protected get proxy(): HTMLElement;
 }
 
+/** Listens for a keyboard shortcut (optionally chorded, e.g. `"ctrl+k, s"`) on a target and fires an `execute` event when matched. */
 declare class PacemShortcutElement extends PacemEventTarget {
+    /** Gets or sets the key combination to listen for (e.g. `"ctrl+s"`, or a comma-separated sequence like `"ctrl+k, s"`). */
     combination: string;
+    /** Gets or sets the event target to listen on; defaults to `window`. */
     target: EventTarget;
     viewActivatedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
@@ -1444,33 +2064,49 @@ declare class PacemShortcutElement extends PacemEventTarget {
     private _shortcutHandler;
 }
 
+/** Sets its own `textContent` to the `text` property, escaping any markup. */
 declare class PacemSpanElement extends PacemSafeContentElement {
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     viewActivatedCallback(): void;
+    /** Gets or sets the plain text to display as this element's content. */
     text: string;
 }
 
+/**
+ * Groups one or more {@link Timeline}s (either {@link AnimationElement} child items or an explicit
+ * `datasource`) and starts/cancels them together, optionally on view activation via `autostart`.
+ */
 declare class PacemStoryboardElement extends PacemItemsContainerElement<AnimationElement> {
+    /** @inheritdoc */
     validate(item: AnimationElement): boolean;
+    /** Gets or sets whether the storyboard starts animating automatically once its view is activated. */
     autostart: boolean;
     /**
      * Extends or contracts the computed duration
      * */
     duration: number;
+    /** Gets or sets the {@link Timeline}s to animate, as an alternative to declaring {@link AnimationElement} child items. */
     datasource: Timeline[];
+    /** @readonly Gets the effective set of {@link Timeline}s in use, resolved from either `datasource` or the child `items`. */
     private _adaptedDatasource;
     viewActivatedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     private _buildDatasourceFromItems;
     private _buildDatasourceFromDatasource;
     private _animate;
+    /** Cancels every running {@link Timeline} in this storyboard. */
     cancelAnimation(): void;
+    /** Starts (or restarts) every {@link Timeline} in this storyboard. */
     startAnimation(): Promise<any>;
 }
 
+/** Injects a `<style>` element into the document `<head>`, populated either inline (`cssText`) or by fetching `src`. */
 declare class PacemStyleProxyElement extends PacemEventTarget {
+    /** Gets or sets the URL of the CSS stylesheet to fetch and inject. */
     src: string;
+    /** Gets or sets the CSS text to inject directly (used when `src` is not set). */
     cssText: string;
+    /** @readonly Gets whether the injected stylesheet (and its web fonts, if any) has finished loading. */
     cssReady: boolean;
     private _style;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
@@ -1480,15 +2116,23 @@ declare class PacemStyleProxyElement extends PacemEventTarget {
     private _fetch;
 }
 
+/**
+ * Pacem Swipe element adapter: implements {@link Swiper} on top of {@link PacemBehavior} to make
+ * registered elements draggable along one axis, with snap points and fling/bounce-back detection.
+ */
 declare class PacemSwipeElement extends PacemBehavior implements Swiper {
     #private;
     /** No return point distance on the horizontal axis (defaults to half the device screen width). */
     snaps: number[];
+    /** Gets or sets the axis along which registered elements can be swiped. */
     direction: 'horizontal' | 'vertical';
+    /** Gets or sets the fine-tuning options (see {@link SwipeOptions}). */
     options: Partial<SwipeOptions>;
     /** Handle selector to be matched when starting the drag gesture. */
     handleSelector: string;
+    /** Wires up the `pointerdown` listener that arms the swipe gesture on the given element. */
     protected decorate(element: Element): void;
+    /** Removes the listener set up by {@link decorate}. */
     protected undecorate(element: Element): void;
     viewActivatedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
@@ -1499,13 +2143,16 @@ declare class PacemSwipeElement extends PacemBehavior implements Swiper {
     private _undoHandler;
 }
 
+/** Redirects consumers (e.g. {@link PacemRepeaterElement}) to an external `<template>` element, firing a `templatechange` event when it changes. */
 declare class PacemTemplateProxyElement extends /*PacemEventTarget*/ TemplateElement {
+    /** Gets or sets the external `<template>` element this proxy points to. */
     target: HTMLTemplateElement;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     addEventListener(type: 'templatechange', listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
     removeEventListener(type: 'templatechange', listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
 }
 
+/** Renders the `text` property as its own plain-text content, replacing any existing child markup. */
 declare class PacemTextElement extends HTMLElement implements OnPropertyChanged, OnConnected {
     constructor();
     private _text;
@@ -1517,8 +2164,10 @@ declare class PacemTextElement extends HTMLElement implements OnPropertyChanged,
     text: string;
 }
 
+/** Fires a `tick` event on a regular interval, as long as it's enabled and `interval` is greater than zero. */
 declare class PacemTimerElement extends PacemEventTarget {
     constructor();
+    /** Gets or sets the tick interval, in milliseconds. */
     interval: number;
     private _handle;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
@@ -1527,13 +2176,16 @@ declare class PacemTimerElement extends PacemEventTarget {
     private _restart;
 }
 
+/** Sets `document.title` to `value` whenever it changes. */
 declare class PacemTitleProxyElement extends PacemEventTarget {
+    /** Gets or sets the text to assign to `document.title`. */
     value: string;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     viewActivatedCallback(): void;
     private _update;
 }
 
+/** Base class for elements that move their own content to another DOM location, restoring nothing on disconnect. */
 declare abstract class PacemTransferProxyElement extends PacemEventTarget {
     protected abstract get proxy(): HTMLElement;
     private _dom;
@@ -1544,21 +2196,31 @@ declare abstract class PacemTransferProxyElement extends PacemEventTarget {
     disconnectedCallback(): void;
 }
 
+/** Animates a numeric `value` from `from` to `to` over `duration`, dispatching animation lifecycle events along the way. */
 declare class PacemTweenElement extends PacemEventTarget {
     private _tweener;
     constructor(_tweener?: TweenService);
+    /** Gets or sets the easing function; defaults to a linear tween. */
     easing: (time: number) => number;
+    /** Gets or sets the starting value. */
     from: number;
+    /** Gets or sets the ending value. */
     to: number;
+    /** Gets or sets the animation duration, in milliseconds (default `1000`). */
     duration: number;
+    /** Gets or sets the delay before the animation starts, in milliseconds. */
     delay: number;
+    /** Gets or sets whether the animation is running; setting it to `true` starts (or restarts) the tween. */
     start: boolean;
+    /** @readonly Gets the current animated value. */
     value: number;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Starts the animation programmatically and returns a promise resolved once it completes. */
     run(): Promise<void>;
     private _animate;
 }
 
+/** {@link PacemContentElement} variant that renders `content` verbatim, without any sanitization. */
 declare class PacemUnsafeContentElement extends PacemContentElement {
     protected sanitize(html: string): string | Node;
 }
@@ -1572,15 +2234,23 @@ declare class PacemViewportAwareElement extends PacemEventTarget {
     disconnectedCallback(): void;
 }
 
+/** Wraps a {@link Worker}, sending/receiving messages to/from a web worker script. */
 declare class PacemWebWorkerProxyElement extends PacemEventTarget {
+    /** Gets or sets the message to be posted to the worker. */
     message: any;
-    /** @readonly */
+    /** @readonly Gets the last message received from the worker. */
     result: any;
+    /** Gets or sets the URL of the worker script to instantiate. */
     src: string;
+    /** Gets or sets whether to automatically send `message` as soon as it changes (default `true`). */
     autosend: boolean;
     viewActivatedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     disconnectedCallback(): void;
+    /**
+     * Posts a message to the worker.
+     * @param message Message to send; defaults to the current `message` property
+     */
     send(message?: any): void;
     private _messageHandler;
     private _errorHandler;
@@ -1589,25 +2259,45 @@ declare class PacemWebWorkerProxyElement extends PacemEventTarget {
     private _disposeWorker;
 }
 
+/** The prefix used for CSS custom properties and classes (e.g. `--{PCSS}-font-main`); configurable independently of the element tag prefix {@link P} via `window.Pacem.Configuration.css`, defaults to {@link P}. */
 export declare const PCSS: any;
 
+/** Ready-to-use event listener that only calls `evt.preventDefault()`; handy as an `addEventListener` callback without allocating a closure. */
 export declare const preventDefaultHandler: (evt: Event) => void;
 
+/**
+ * Dispatched whenever a property decorated with {@link Watch} changes value (unless that decorator's
+ * `emit` option is set to `false`). This is the mechanism data-bound expressions listen to in order to
+ * re-evaluate themselves when one of their dependencies changes.
+ */
 export declare class PropertyChangeEvent extends CustomTypedEvent<PropertyChangeEventArgs> {
     constructor(args: PropertyChangeEventArgs);
 }
 
+/** Payload carried by a {@link PropertyChangeEvent}. */
 export declare interface PropertyChangeEventArgs {
+    /** Name of the property that changed (camelCase). */
     propertyName: string;
+    /** Property's previous value, if any. */
     oldValue?: any;
+    /** Property's new value. */
     currentValue: any;
+    /** `true` when this is the property's first observed value (element not fully initialized yet). */
     firstChange?: boolean;
 }
 
+/** Event name dispatched whenever a `@Watch`-decorated property changes value; see {@link PropertyChangeEvent}. */
 export declare const PropertyChangeEventName: string;
 
+/** Signature of a function testing two values of type `T` for equality (used by the {@link Watch} decorator to decide whether a property actually changed). */
 export declare type PropertyComparer<T> = (old: T, val: T) => boolean;
 
+/**
+ * Bridges an element's string attribute value and its typed property value, used by the {@link Watch}
+ * decorator (and the {@link CustomElement} decorator that wires up attribute observation) to convert
+ * attribute strings to property values and, optionally, reflect property values back to attributes.
+ * See {@link PropertyConverters} for the built-in implementations.
+ */
 export declare interface PropertyConverter {
     /** You can assume `attr` not null, cause it will be processed only in that case. */
     readonly convert: (attr: string, element?: HTMLElement) => any;
@@ -1617,6 +2307,11 @@ export declare interface PropertyConverter {
     readonly retryConversionWhenReady?: boolean;
 }
 
+/**
+ * Built-in {@link PropertyConverter} implementations, keyed by the type they convert to/from. Passed as
+ * the `converter` option of a {@link Watch}-decorated property (e.g. `@Watch({ converter: PropertyConverters.Number })`)
+ * to control how that property's attribute string is parsed and, on change, reflected back.
+ */
 export declare const PropertyConverters: {
     None: PropertyConverter;
     String: PropertyConverter;
@@ -1634,10 +2329,12 @@ export declare const PropertyConverters: {
     Size: PropertyConverter;
 };
 
+/** A map of binding-dependent property names to their {@link PropertyDependency} descriptor. */
 export declare type PropertyDependencies = {
     [name: string]: PropertyDependency;
 };
 
+/** Describes a single data-binding dependency: one property of one element that a bound expression relies upon. */
 export declare type PropertyDependency = {
     /** Element to depend upon */
     element: Node;
@@ -1650,6 +2347,7 @@ export declare type PropertyDependency = {
     twowayAllowed: boolean;
 };
 
+/** Static regular-expression helpers. */
 export declare class Regex {
     /**
      * Splits an input string into segments based on a matching pattern.
@@ -1659,16 +2357,19 @@ export declare class Regex {
     static split(input: string, pattern: RegExp): RegexMatchSegment[];
 }
 
+/** One chunk produced by {@link Regex.split}: either a literal, non-matching substring or a matched one. */
 export declare type RegexMatchSegment = {
     value: string;
     match: boolean;
     index: number;
 };
 
+/** Minimal shape of an element that repeats a template once per item of a `datasource` array (e.g. `PacemRepeaterElement`). */
 export declare interface Repeater extends HTMLElement {
     datasource: any[];
 }
 
+/** Static lookup helpers for locating the {@link RepeaterItem} context a given element belongs to. */
 export declare class Repeater {
     /**
      * Seeks for a PacemRepeaterItem element upwards through the DOM tree, given a starting element and the number of nesting levels.
@@ -1678,15 +2379,37 @@ export declare class Repeater {
     static findItemContext(element: Element, upLevels?: number, logFn?: (message?: string) => void): RepeaterItem;
 }
 
+/**
+ * Base class tracking a single rendered repetition of a {@link Repeater}'s template: it associates a
+ * DOM placeholder node with the `item`/`index` scope values that template's binding expressions
+ * evaluate against, and is itself attached to that placeholder (see {@link getRepeaterItem}) so
+ * descendant elements can find their way back to it via {@link findUpwards}.
+ */
 export declare abstract class RepeaterItem {
     private _placeholder;
+    /**
+     * Seeks upwards from `element` (previous siblings, then parent, repeated) for the nearest ancestor
+     * placeholder tagged as a {@link RepeaterItem}, skipping `upLevels` matches before returning one -
+     * this is how deeply-nested repeaters resolve which repetition (of which ancestor repeater) an
+     * expression's `^item`/`^^item`/... token refers to.
+     * @param element Element to start the upward search from.
+     * @param upLevels 0-based number of matching ancestors to skip before returning one (`0` = nearest).
+     * @param logFn Called with a warning message if no match is found and `element` is connected to the DOM.
+     */
     static findUpwards(element: Element, upLevels?: number, logFn?: (message?: string) => void): RepeaterItem;
+    /** Tests whether `node` is the placeholder of some {@link RepeaterItem}. */
     static isRepeaterItem(node: Node): boolean;
+    /** Retrieves the {@link RepeaterItem} attached to `node`, if `node` is a repeater-item placeholder; see {@link isRepeaterItem}. */
     static getRepeaterItem(node: Node): RepeaterItem;
+    /** @param _placeholder DOM node (typically a comment) that stands in for this repetition and gets tagged so {@link getRepeaterItem} can retrieve this instance back from it. */
     constructor(_placeholder: Node);
+    /** The data item this repetition renders. */
     abstract item: any;
+    /** The 0-based position of this repetition within its {@link Repeater}'s `datasource`. */
     abstract index: number;
+    /** The {@link Repeater} element this repetition belongs to. */
     abstract readonly repeater: Repeater;
+    /** The DOM placeholder node standing in for this repetition. */
     get placeholder(): Node;
 }
 
@@ -1733,7 +2456,8 @@ declare class RepeaterItemRemoveEvent extends RepeaterItemEvent {
 
 declare const RepeaterItemRemoveEventName = "repeateritemremove";
 
-/** @deprecated */
+/** Options accepted by {@link Http.request}.
+ * @deprecated */
 declare type RequestOptions = {
     data?: 'string' | {
         [key: string]: string;
@@ -1745,10 +2469,16 @@ declare type RequestOptions = {
     progress?: (pct: number) => void;
 };
 
+/**
+ * Custom UI event dispatched throughout the rescale gesture lifecycle (see {@link RescaleEventType}).
+ */
 declare class RescaleEvent extends CustomUIEvent<RescaleEventArgsClass> {
     constructor(type: RescaleEventType, args: RescaleEventArgsClass, eventInit?: EventInit, evt?: MouseEvent | TouchEvent);
 }
 
+/**
+ * Plain data shape backing {@link RescaleEventArgsClass}.
+ */
 declare type RescaleEventArgs = {
     element: HTMLElement | SVGElement;
     origin: Point;
@@ -1758,39 +2488,73 @@ declare type RescaleEventArgs = {
     targetRect?: Rect;
 };
 
+/**
+ * Read-only event args dispatched with the rescale gesture lifecycle events.
+ */
 declare class RescaleEventArgsClass {
     private _builder;
     private constructor();
+    /** @readonly Gets the current pointer position. */
     get currentPosition(): Point;
+    /** @readonly Gets the rectangle the element is being resized to. */
     get targetRect(): Rect;
+    /** @readonly Gets the element being resized. */
     get element(): HTMLElement | SVGElement;
+    /** @readonly Gets the handle being dragged (see {@link RescaleHandle}). */
     get handle(): string;
+    /** Builds a new {@link RescaleEventArgsClass} out of a plain {@link RescaleEventArgs} builder. */
     static fromArgs(builder: RescaleEventArgs): RescaleEventArgsClass;
 }
 
+/**
+ * Enumerates the events dispatched throughout the rescale gesture lifecycle.
+ */
 declare enum RescaleEventType {
+    /** First rescaling act. */
     Start = "rescalestart",
+    /** Any rescaling act. */
     Rescale = "rescale",
+    /** Terminating the rescaling activities. */
     End = "rescaleend"
 }
 
+/**
+ * Enumerates the resize handles a {@link Rescaler} can expose around a rescalable element.
+ */
 declare enum RescaleHandle {
+    /** All four sides/corners are enabled. */
     All = "all",
+    /** The top edge (and its corners) is enabled. */
     Top = "top",
+    /** The left edge (and its corners) is enabled. */
     Left = "left",
+    /** The right edge (and its corners) is enabled. */
     Right = "right",
+    /** The bottom edge (and its corners) is enabled. */
     Bottom = "bottom"
 }
 
+/**
+ * Interface to be implemented in order to create a proper rescale adapter.
+ */
 declare interface Rescaler {
+    /** Gets or sets the resize handles enabled on the rescalable element(s). */
     handles: RescaleHandle[];
+    /** Gets or sets the minimum allowed width, in pixels. */
     minWidth: number;
+    /** Gets or sets the maximum allowed width, in pixels. */
     maxWidth: number;
+    /** Gets or sets the maximum allowed height, in pixels. */
     maxHeight: number;
+    /** Gets or sets the minimum allowed height, in pixels. */
     minHeight: number;
+    /** Gets or sets whether the width/height ratio must be preserved while resizing. */
     keepProportions: boolean;
+    /** Registers a listener for a rescale lifecycle event. */
     addEventListener(evt: RescaleEventType, listener: (evt: RescaleEvent) => void, useCapture?: boolean): void;
+    /** Unregisters a listener previously added for a rescale lifecycle event. */
     removeEventListener(evt: RescaleEventType, listener: (evt: RescaleEvent) => void, useCapture?: boolean): void;
+    /** Dispatches a rescale lifecycle event. */
     dispatchEvent(evt: RescaleEvent): boolean;
 }
 
@@ -1807,8 +2571,10 @@ declare type ResizeEventArgs = {
 
 declare const ResizeEventName = "resize";
 
-/** @deprecated */
+/** Wraps a completed `XMLHttpRequest` produced by {@link Http.request}, exposing its status, headers and body in convenient forms.
+ * @deprecated */
 declare class Response_2 {
+    /** @param req The completed `XMLHttpRequest`. @param processTime Elapsed request time, in milliseconds. */
     constructor(req: XMLHttpRequest, processTime: number);
     private _processTime;
     private _status;
@@ -1817,17 +2583,26 @@ declare class Response_2 {
     private _type;
     private _allHeadersRaw;
     private _headers;
+    /** Elapsed request time, in milliseconds. */
     get processTime(): number;
+    /** Response headers, parsed into a name/value map (lazily, on first access). */
     get headers(): {
         [key: string]: string;
     };
+    /** The `Content-Length` response header, parsed as a number. */
     get size(): number;
+    /** The `Content-Type` response header. */
     get mime(): string;
+    /** The `Date` response header, parsed into a `Date`. */
     get date(): Date;
     private _parseHeaders;
+    /** HTTP status code. */
     get status(): number;
+    /** Raw response body as text. */
     get text(): string;
+    /** Response body, typed per `XMLHttpRequest.responseType` (see {@link type}). */
     get content(): any;
+    /** The `XMLHttpRequest.responseType` used for this request. */
     get type(): string;
     /**
      * Short-hand utility for getting or parsing json content (if any).
@@ -1835,10 +2610,16 @@ declare class Response_2 {
     get json(): any;
 }
 
+/**
+ * Custom UI event dispatched throughout the rotate gesture lifecycle (see {@link RotateEventType}).
+ */
 declare class RotateEvent extends CustomUIEvent<RotateEventArgsClass> {
     constructor(type: RotateEventType, args: RotateEventArgsClass, eventInit?: EventInit, evt?: MouseEvent | TouchEvent);
 }
 
+/**
+ * Plain data shape backing {@link RotateEventArgsClass}.
+ */
 declare type RotateEventArgs = {
     element: HTMLElement | SVGElement;
     origin: Point;
@@ -1851,23 +2632,41 @@ declare type RotateEventArgs = {
     rotation: number;
 };
 
+/**
+ * Read-only event args dispatched with the rotate gesture lifecycle events.
+ */
 declare class RotateEventArgsClass {
     private _builder;
     private constructor();
+    /** @readonly Gets the current pointer position. */
     get currentPosition(): Point;
+    /** @readonly Gets the current rotation, in radians. */
     get rotation(): number;
+    /** @readonly Gets the element being rotated. */
     get element(): HTMLElement | SVGElement;
+    /** @readonly Gets the pivot point the element is rotating around. */
     get center(): Point;
+    /** Builds a new {@link RotateEventArgsClass} out of a plain {@link RotateEventArgs} builder. */
     static fromArgs(builder: RotateEventArgs): RotateEventArgsClass;
 }
 
+/**
+ * Enumerates the events dispatched throughout the rotate gesture lifecycle.
+ */
 declare enum RotateEventType {
+    /** First rotating act. */
     Start = "rotatestart",
+    /** Any rotating act. */
     Rotate = "rotate",
+    /** Terminating the rotating activities. */
     End = "rotateend"
 }
 
+/**
+ * Interface to be implemented in order to create a proper rotate adapter.
+ */
 declare interface Rotator {
+    /** Gets or sets the pivot point the element rotates around; defaults to the element's own center. */
     center?: Point;
     /** Gets or sets the minimum allowed rotation in radians */
     minRotation?: number;
@@ -1875,35 +2674,47 @@ declare interface Rotator {
     maxRotation?: number;
     /** Gets or sets the step constrained amount in radians */
     step?: number;
+    /** Registers a listener for a rotate lifecycle event. */
     addEventListener(evt: RotateEventType, listener: (evt: RotateEvent) => void, useCapture?: boolean): void;
+    /** Unregisters a listener previously added for a rotate lifecycle event. */
     removeEventListener(evt: RotateEventType, listener: (evt: RotateEvent) => void, useCapture?: boolean): void;
+    /** Dispatches a rotate lifecycle event. */
     dispatchEvent(evt: RotateEvent): boolean;
 }
 
+/** Metadata describing one named `{segment}` of a route template, as parsed by `Utils.URIs.parseRoute`. */
 declare type RouteMetadata = {
     name: string;
     optional: boolean;
     index: number;
 };
 
-declare class RouterNavigateEvent extends CustomTypedEvent<RouterNavigateEventArgs> {
+/** Dispatched by a router once it has navigated to a new `path` (not cancelable — the navigation already happened). */
+export declare class RouterNavigateEvent extends CustomTypedEvent<RouterNavigateEventArgs> {
+    /** @param path Either the destination path alone, or the full navigation args (path, title, referrer). */
     constructor(path: string | RouterNavigateEventArgs);
 }
 
-declare type RouterNavigateEventArgs = {
+/** Payload carried by a {@link RouterNavigateEvent}. */
+export declare type RouterNavigateEventArgs = {
     path: string;
     title?: string;
     referrer?: string;
 };
 
-declare const RouterNavigateEventName = "navigate";
+/** Event name dispatched by a router *after* a navigation has been committed; see {@link RouterNavigateEvent}. */
+export declare const RouterNavigateEventName = "navigate";
 
-declare class RouterNavigatingEvent extends CustomTypedEvent<string> {
+/** Dispatched by a router right before navigating to `path`; cancelable, so a listener can call `preventDefault()` to abort the navigation. */
+export declare class RouterNavigatingEvent extends CustomTypedEvent<string> {
+    /** @param path Destination path about to be navigated to. */
     constructor(path: string);
 }
 
-declare const RouterNavigatingEventName = "navigating";
+/** Event name dispatched by a router *before* a navigation is committed; see {@link RouterNavigatingEvent}. Cancelable: calling `preventDefault()` aborts the navigation. */
+export declare const RouterNavigatingEventName = "navigating";
 
+/** Parsed representation of a router's current location: path segments (declared as route metadata) become named properties, alongside the fixed `$path`/`$pathname`/`$query`/`$hash`/`$scrollY` keys. */
 export declare type RouterState = {
     [key: string]: string;
 } & {
@@ -1914,6 +2725,7 @@ export declare type RouterState = {
         [key: string]: string;
     };
     $hash?: string;
+    $scrollY?: number;
 };
 
 declare class ScrollEvent extends CustomTypedEvent<ScrollEventArgs> {
@@ -1939,14 +2751,24 @@ declare interface StateEventArgs<T> {
 
 declare type StateEventType = 'push' | 'undo' | 'reset' | 'redo';
 
+/** Error thrown by {@link Http.request} when a request fails outright or completes with a non-2xx status. */
 declare class StatusCodeError extends Error {
     private statusCode;
+    /** @param statusCode HTTP status code (`500` for network-level failures). @param statusText Status text / error message. */
     constructor(statusCode: number, statusText: string);
+    /** The HTTP status code that caused this error. */
     get status(): number;
 }
 
+/** Ready-to-use event listener that only calls `evt.stopPropagation()`; handy as an `addEventListener` callback without allocating a closure. */
 export declare const stopPropagationHandler: (evt: Event) => void;
 
+/**
+ * JSON-serializing wrapper around `sessionStorage`/`localStorage` that transparently supports per-key
+ * expiration: values stored with a `duration` are stamped with an expiry timestamp and evicted lazily
+ * (checked on the next {@link getPropertyValue} call for that key, not via a timer). Session storage and
+ * local storage are treated as a single logical namespace - storing a key in one clears any same-named entry in the other.
+ */
 declare class Storage_2 {
     private _getStorage;
     private _parseValue;
@@ -1964,16 +2786,29 @@ declare class Storage_2 {
      * @param duration Storage timeout in seconds
      */
     setPropertyValue(name: string, value: any, duration: number): any;
+    /**
+     * Retrieves a previously stored value by `name`, checking session storage first, then local storage.
+     * Returns `null` if not found, or if found but past its expiration.
+     * @param name The unique key.
+     */
     getPropertyValue(name: string): any;
+    /** Clears both session and local storage entirely. */
     clear(): void;
+    /** Removes a single entry by `name` from both session and local storage. */
     removeProperty(name: string): void;
 }
 export { Storage_2 as Storage }
 
+/**
+ * Custom typed event dispatched throughout the swipe gesture lifecycle (see {@link SwipeEventType}).
+ */
 declare class SwipeEvent extends CustomTypedEvent<SwipeEventArgsClass> {
     constructor(type: SwipeEventType, args: SwipeEventArgsClass, eventInit?: EventInit);
 }
 
+/**
+ * Plain data shape backing {@link SwipeEventArgsClass}.
+ */
 declare type SwipeEventArgs = {
     horizontalspeed?: number;
     verticalspeed?: number;
@@ -1989,10 +2824,14 @@ declare type SwipeEventArgs = {
     vertical?: boolean;
 };
 
+/**
+ * Read-only event args dispatched with the swipe gesture lifecycle events.
+ */
 declare class SwipeEventArgsClass {
     #private;
     private _builder;
     private constructor();
+    /** @readonly Gets the resolved swipe direction (`'up'`, `'down'`, `'left'` or `'right'`). */
     get direction(): "down" | "left" | "right" | "up";
     /** Speed in pixels/second, with sign. */
     get speed(): number;
@@ -2003,24 +2842,43 @@ declare class SwipeEventArgsClass {
     get predictedDelta(): number;
     /** Seconds to reach the final predicted position. */
     get predictedDuration(): number;
+    /** @readonly Gets the element being swiped. */
     get element(): HTMLElement | SVGElement;
+    /** Builds a new {@link SwipeEventArgsClass} out of a plain {@link SwipeEventArgs} builder. */
     static fromArgs(builder: SwipeEventArgs): SwipeEventArgsClass;
 }
 
+/**
+ * Enumerates the events dispatched throughout the swipe gesture lifecycle.
+ */
 declare enum SwipeEventType {
+    /** Dispatched when the swipe gesture ends (release). */
     Swipe = "swipe",
+    /** Dispatched while the pointer is dragging the element around. */
     Pan = "pan",
+    /** Dispatched when the swipe ends and its resolved direction is leftward. */
     SwipeLeft = "swipeleft",
+    /** Dispatched when the swipe ends and its resolved direction is rightward. */
     SwipeRight = "swiperight",
+    /** Dispatched when the swipe ends and its resolved direction is upward. */
     SwipeUp = "swipeup",
+    /** Dispatched when the swipe ends and its resolved direction is downward. */
     SwipeDown = "swipedown",
+    /** Dispatched when the snap/bounce-back animation following a swipe completes. */
     SwipeAnimationEnd = "swipeanimationend",
+    /** Dispatched when the snap/bounce-back animation following a leftward swipe completes. */
     SwipeLeftAnimationEnd = "swipeleftanimationend",
+    /** Dispatched when the snap/bounce-back animation following a rightward swipe completes. */
     SwipeRightAnimationEnd = "swiperightanimationend",
+    /** Dispatched when the snap/bounce-back animation following an upward swipe completes. */
     SwipeUpAnimationEnd = "swipeupanimationend",
+    /** Dispatched when the snap/bounce-back animation following a downward swipe completes. */
     SwipeDownAnimationEnd = "swipedownanimationend"
 }
 
+/**
+ * Fine-tuning options for the {@link PacemSwipeElement} swipe/pan gesture.
+ */
 declare type SwipeOptions = {
     /** Inertia on release. */
     inertia: number;
@@ -2039,64 +2897,141 @@ declare type SwipeOptions = {
     bouncy: boolean;
 };
 
+/**
+ * Interface to be implemented in order to create a proper swipe adapter.
+ */
 declare interface Swiper {
     /** Anchoring targets. */
     readonly snaps: number[];
     /** Swipe direction. */
     readonly direction: 'vertical' | 'horizontal';
+    /** Registers a listener for a swipe lifecycle event. */
     addEventListener(evt: SwipeEventType, listener: (evt: SwipeEvent) => void, useCapture?: boolean): void;
+    /** Unregisters a listener previously added for a swipe lifecycle event. */
     removeEventListener(evt: SwipeEventType, listener: (evt: SwipeEvent) => void, useCapture?: boolean): void;
+    /** Dispatches a swipe lifecycle event. */
     dispatchEvent(evt: SwipeEvent): boolean;
 }
 
+/** Marker base class for elements that behave like `<template>` (e.g. a custom template-proxy element), so template-detection logic can treat them the same as a native `HTMLTemplateElement`. */
 export declare abstract class TemplateElement extends HTMLElement {
 }
 
+/**
+ * Method decorator that throttles calls to an instance method: the first call in a window runs immediately;
+ * further calls arriving before the window elapses are not dropped but coalesced — only the most recent
+ * set of arguments is remembered and, once the window elapses, one trailing call runs with those arguments
+ * (mirroring a classic "leading + trailing" throttle).
+ *
+ * @param msecs Throttle window in milliseconds, or `true` to use a single animation frame (`requestAnimationFrame`) as the window. Defaults to `50`.
+ * @param keyFactory Computes the per-instance timer key from the method name and call arguments; override to scope throttling per argument instead of per method. Defaults to a single shared key per method.
+ * @returns A method decorator to apply to the instance method to throttle.
+ */
 export declare function Throttle(msecs?: true | number, keyFactory?: (key: String, ...args: any[]) => string): (target: any, key: string, descriptor?: PropertyDescriptor) => void;
 
+/**
+ * Contract for a single animatable timeline entry (e.g. an {@link AnimationElement}) that a storyboard/host can start and cancel.
+ */
 declare interface Timeline {
+    /** Gets or sets the element whose property is animated. */
     target: Element;
+    /** Gets or sets the name of the animated property on `target`. */
     property: string;
+    /** Gets or sets the delay before the animation starts, in milliseconds. */
     delay: number;
+    /** Gets or sets the animation duration, in milliseconds. */
     duration: number;
+    /** Gets or sets the easing function applied to the animation progress. */
     easing: Easing;
+    /** Gets or sets the number of times the animation repeats. */
     iterations: number;
+    /** Gets or sets the playback direction of the animation. */
     direction: PlaybackDirection;
+    /** Starts (or restarts) the animation. */
     startAnimation(): any;
+    /** Cancels the running animation. */
     cancelAnimation(): any;
 }
 
+/**
+ * `requestAnimationFrame`-driven timer that invokes a callback at (approximately) a given frame rate.
+ * Instances are created via the static {@link Timer.run} factory rather than `new`.
+ */
 declare class Timer {
     #private;
     private constructor();
     private _run;
+    /**
+     * Creates and starts a new {@link Timer}.
+     * @param callback Invoked on every tick with the current frame timestamp.
+     * @param fps Target frame rate, in frames per second (default `60`).
+     */
     static run(callback: (time?: number) => void, fps?: number): Timer;
+    /** Stops the timer, cancelling any pending animation frame. */
     stop(): void;
 }
 
+/**
+ * Method decorator that registers a static/instance method as a globally-named {@link TransformFunction},
+ * making it callable by name from template binding expressions (e.g. `{{ ^value | myTransform }}`).
+ * The registration is global (attached under `Utils.core`, dot-segmented by `name`), not per-instance.
+ *
+ * @param name Dot-separated registration path (e.g. `'strings.upper'`); segments before the last create/reuse nested namespaces under `Utils.core`. Defaults to the decorated method's own name when omitted.
+ * @returns A method decorator to apply to the transform function.
+ */
 declare function Transformer_2(name?: string): (target: any, key: string, descriptor?: PropertyDescriptor) => void;
 export { Transformer_2 as Transformer }
 
+/** Signature of a function registered via the {@link Transformer} decorator: a named, globally reusable value-transforming function usable in template expressions. */
 export declare type TransformFunction = (value?: any, ...args: any[]) => any;
 
+/**
+ * Base class for animation elements that interpolate their `from`/`to` value via {@link TweenService}.
+ * Concrete subclasses only need to supply {@link tweenInterpolationCallback} to map normalized progress to a value of type `T`.
+ */
 declare abstract class TweenAnimationElement<T> extends AnimationElement {
     #private;
     private _tweener;
     constructor(_tweener?: TweenService);
+    /** @readonly Gets the {@link TweenService} instance driving this animation. */
     protected get tweener(): TweenService;
+    /** Gets or sets the starting value of type `T`. */
     abstract from: T;
+    /** Gets or sets the ending value of type `T`. */
     abstract to: T;
+    /** Starts (or restarts) the tween and returns a promise resolved once it completes. */
     startAnimation(): Promise<void>;
+    /** Cancels the running tween. */
     cancelAnimation(): void;
+    /**
+     * Maps the tween's normalized time/progress to the interpolated value of type `T` to assign to `target[property]`.
+     * @param time Normalized elapsed time, in `[0,1]`.
+     * @param progress Eased progress (i.e. `time` run through {@link easing}).
+     */
     protected abstract tweenInterpolationCallback(time: number, progress: number): T;
 }
 
+/**
+ * Runs `requestAnimationFrame`-driven numeric tweens between two values, invoking a callback on each frame.
+ */
 declare class TweenService {
+    /**
+     * Tweens a numeric value from `from` to `to` over `duration` milliseconds, invoking `callback` on every animation frame.
+     * @param from Starting value.
+     * @param to Ending value.
+     * @param duration Tween duration, in milliseconds.
+     * @param delay Delay before the tween starts, in milliseconds (default `0`).
+     * @param easing Easing function applied to the normalized `[0,1]` time (defaults to {@link Easings.linear}).
+     * @param callback Invoked on every frame (and once more with `time === 1.0`) with the normalized time and the current value.
+     * @returns A promise resolved when the tween completes.
+     */
     run(from: number, to: number, duration: number, delay?: number, easing?: (time: number) => number, callback?: (time: number, value: number) => void): Promise<void>;
 }
 
+/** Runtime value (aliasing the built-in `Function`) usable where a constructor reference is needed as a value, paired with the {@link Type} interface for typing it. */
 export declare const Type: FunctionConstructor;
 
+/** A constructor reference for a class producing instances of `T`. */
 export declare interface Type<T> extends Function {
     new (...args: any[]): T;
 }
@@ -2131,6 +3066,7 @@ export declare namespace UI {
     }
 }
 
+/** Minimal shape of a native UI event: keyboard modifiers plus pointer coordinates in all three coordinate systems. Implemented by {@link CustomUIEvent}. */
 export declare interface UIEventLike extends KeyEventLike {
     readonly clientX: number;
     readonly clientY: number;
@@ -2140,13 +3076,26 @@ export declare interface UIEventLike extends KeyEventLike {
     readonly screenY: number;
 }
 
+/**
+ * The framework's static utility grab-bag: general helpers plus namespaced sub-modules (`Json`, `Dates`,
+ * `Css`, `Strings`, `Blobs`, `Images`, `Browsers`, `Cookies`, `URIs`) re-exposing (and in some cases
+ * extending) functionality from `@pacem/pacem-foundation`. Also the home of `Utils.core`, the global
+ * registry object used for cross-cutting framework state (e.g. registered {@link Transformer}s).
+ */
 export declare class Utils {
+    /** The framework's global scratch/registry object (`window[id]`, where `id` defaults to `'pacem'` and is configurable via `window.Pacem.Configuration.core`); created on first access. Used e.g. to store {@link Transformer}-registered transform functions. */
     static get core(): any;
+    /** The platform's (native or polyfilled) `customElements` registry. */
     static get customElements(): any;
+    /** Generates a unique numeric-ish id string. */
     static uniqueId(): number;
+    /** Generates a unique short code string. */
     static uniqueCode(): string;
+    /** Generates a random string of the given `length`. */
     static randomString(length: number): string;
+    /** Parses a date-like value (ISO string, `Date`, or timestamp) into a `Date`. */
     static parseDate(input: string | Date | number): Date;
+    /** Writes `input` to the system clipboard, using the async Clipboard API when available and falling back to `document.execCommand('copy')` otherwise. */
     static copyToClipboard(input: string): Promise<void>;
     static Json: {
         stringify: typeof Json.serialize;
@@ -2167,19 +3116,30 @@ export declare class Utils {
         addDays: typeof Dates.addDays;
         daysBetween: typeof Dates.daysBetween;
     };
+    /**
+     * Computes a CSS `filter` value that tints black/grayscale content towards the given color (via a
+     * `brightness`/`sepia`/`hue-rotate`/`saturate`/`brightness` chain), and either applies it directly to
+     * `element.style.filter` or returns it as a string.
+     * @param element When provided, the filter is applied directly to this element's `style.filter` instead of being returned.
+     * @param rgb Target color, as a CSS color string or an `[r, g, b]` tuple.
+     */
     static colorize(element: HTMLElement, rgb: string | [number, number, number]): void;
     static colorize(rgb: string | [number, number, number]): string;
+    /** Escapes `input` for safe use as a CSS identifier/selector fragment. */
     static cssEscape(input: string): string;
     static Css: {
         colorize: typeof Utils.colorize;
         escape: typeof Utils.cssEscape;
+        /** Reads a CSS custom property's current value off the document root (`:root`/`html`). */
         getVariableValue(name: string): string;
+        /** Sets a CSS custom property's value on the document root (`:root`/`html`). */
         setVariable(name: string, value: string): void;
         /**
          * Naive O(n^2) implementation for an actual css class presence (definition) in the current DOM.
          * @param name CSS class name
          */
         isClassDefined(name: string): boolean;
+        /** Parses an element's (or style declaration's) computed `transform: matrix(...)` CSS value into its 2D affine matrix components; identity if unset. */
         deserializeTransform(element: Element | CSSStyleDeclaration): Matrix2D;
     };
     static leftPad: typeof Strings.leftPad;
@@ -2189,6 +3149,7 @@ export declare class Utils {
         leftPad: typeof Strings.leftPad;
         format: typeof Strings.format;
         diff: typeof Strings.diff;
+        /** Strips HTML markup from `html`, returning its plain-text content. */
         stripHTML: (html: string) => string;
     };
     static Blobs: {
@@ -2201,10 +3162,15 @@ export declare class Utils {
         load: typeof Imaging.loadImage;
         resize: typeof Imaging.resizeImage;
     };
+    /** Loads an image from `src` and resolves with the `HTMLImageElement` once ready (or rejects on error). */
     static loadImage(src: string): Promise<HTMLImageElement>;
+    /** Converts a `Blob` to a `data:` URL string. */
     static blobToDataURL(blob: Blob): Promise<string>;
+    /** Converts a `data:` URL string back into a `Blob`. */
     static dataURLToBlob(dataURL: string): Blob;
+    /** Reads a `Blob`'s content as text, using the given `encoding` (default UTF-8). */
     static blobToText(blob: Blob, encoding?: string): Promise<string>;
+    /** Wraps `content` in a `Blob` of the given MIME `type` (default `'text/plain'`). */
     static textToBlob(content: string, type?: string): Blob;
     /** @deprecated Use {Utils.Images.resize}, instead.
      * Resizes an image when exceeding the provided size constraints.
@@ -2221,6 +3187,7 @@ export declare class Utils {
      * @param ctx
      */
     static cropImage(url: string, width?: number, height?: number, quality?: number): PromiseLike<string>;
+    /** Returns the list of vendor-prefixed `getUserMedia` implementations available on `navigator`, if any. */
     static getUserMediaFunctions(): any[];
     /**
      * Crops the snapshot of a drawable element onto a provided canvas context. It gets centered in the area and cropped (`cover`-like behavior).
@@ -2239,10 +3206,22 @@ export declare class Utils {
      * @param quality Quality ratio between 0..1
      */
     static snapshotElement(el: HTMLElement | SVGElement, background?: string, type?: string, quality?: number): Promise<Blob>;
+    /**
+     * Triggers a client-side file download, either of an in-memory `Blob` or by fetching a `url` first
+     * (in which case the filename is inferred, when not given, from the `Content-Disposition` response
+     * header, falling back to `'download'`).
+     * @param content In-memory content to download.
+     * @param url URL to fetch and download the response body of.
+     * @param filename Suggested file name.
+     * @param options When downloading from a `url`: filename, MIME type override, and fetch `credentials`/`headers`.
+     * @param mime MIME type hint used when downloading a raw `Blob`. Defaults to `'application/download'`.
+     */
     static download(content: Blob, filename?: string, mime?: string): Promise<void>;
     static download(url: string, filename?: string, mime?: string): Promise<void>;
     static download(url: string, options: DownloadOptions): Promise<void>;
+    /** Whether the document (including module scripts) has fully finished loading (`document.readyState === 'complete'`). */
     static isDOMReady(): boolean;
+    /** Registers `listener` to run once the document (and its resources, e.g. images) has fully loaded (the `window` `'load'` event). */
     static onDOMReady(listener: EventListenerOrEventListenerObject): void;
     /**
      * Moves all the source element children to the target element and returns them as an array of nodes.
@@ -2256,25 +3235,41 @@ export declare class Utils {
      * @param target Target element.
      */
     static moveItems(nodes: Node[] | NodeList, target: Element): Node[];
+    /** Cross-browser `Element.matches(selector)`, falling back to vendor-prefixed variants. */
     static is(el: any, selector: string): boolean;
+    /** Resolves the effective language for `el`: its own `lang` attribute, else the document's, else the browser's. */
     static lang(el: HTMLElement): string;
+    /** JSON-stringifies `obj` (via {@link Json}), or passes through `null`/`undefined` unchanged. */
     static jsonSortStringify(obj: {}): string;
     static Browsers: {
         detect: typeof detect;
     };
+    /** Parses a `document.cookie`-style string (or `document.cookie` itself, by default) into a name/value map. */
     static cookies(cookie?: string): Record<string, string>;
+    /** Cookie helpers, preferring the native `cookieStore` API when available and falling back to `document.cookie` parsing otherwise. */
     static Cookies: {
+        /** Retrieves all cookies (or just `cookieName`, if given) as {@link CookieData} entries. */
         getAll: (cookieName?: string) => Promise<CookieData[]>;
+        /** Serializes a {@link CookieData} descriptor into a `document.cookie`-assignable string (including `domain`/`path`/`max-age`/`expires`/`Partitioned`/`SameSite`/`Secure` attributes, as provided). */
         stringify: (data: CookieData) => string;
     };
+    /** Tests whether `el` is currently visible (via the `checkVisibility` API when available, falling back to a CSS-visibility/size heuristic). */
     static isVisible(el: HTMLElement | SVGElement): boolean;
+    /** Tests whether `el` has `className` set, using `classList` when available (with a regex-based fallback). */
     static hasClass(el: HTMLElement | SVGElement, className: string): boolean;
+    /** Adds one or more (space-separated) classes to `el`, using `classList` when available. */
     static addClass(el: HTMLElement | SVGElement, className: string): void;
+    /** Removes one or more (space-separated) classes from `el`, using `classList` when available. */
     static removeClass(el: HTMLElement | SVGElement, className: string): void;
+    /** Adds or removes `className` on `el` depending on `on`; see {@link addClass}/{@link removeClass}. */
     static toggleClass(el: HTMLElement | SVGElement, className: string, on: boolean): void;
+    /** Tests whether `el`'s `part` attribute (CSS Shadow Parts) contains `partName`. */
     static hasPart(el: HTMLElement | SVGElement, partName: string): boolean;
+    /** Adds one or more (space-separated) shadow-part names to `el`'s `part` attribute. */
     static addPart(el: HTMLElement | SVGElement, partName: string): void;
+    /** Removes one or more (space-separated) shadow-part names from `el`'s `part` attribute. */
     static removePart(el: HTMLElement | SVGElement, partName: string): void;
+    /** Adds or removes `partName` on `el`'s `part` attribute depending on `on`; see {@link addPart}/{@link removePart}. */
     static togglePart(el: HTMLElement | SVGElement, partName: string, on: boolean): void;
     /**
      * Retrieve the bounding box of the provided element as of its rendered appearance on the stage (takes transformations into account).
@@ -2291,7 +3286,9 @@ export declare class Utils {
      * @param el The element.
      */
     static offsetRect(el: Element): Rect;
+    /** Sums `offsetTop` up the `offsetParent` chain, giving `el`'s vertical position relative to the document rather than just its nearest positioned ancestor. */
     static naturalOffsetTop(el: HTMLElement): number;
+    /** Sums `offsetTop` up the `offsetParent` chain (note: mirrors {@link naturalOffsetTop}'s calculation, not `offsetLeft`), giving `el`'s horizontal position relative to the document. */
     static naturalOffsetLeft(el: HTMLElement): number;
     /**
      * Retrieve the natural bounding box of the provided element (does not takes transformations into account).
@@ -2310,10 +3307,23 @@ export declare class Utils {
     static naturalOffsetRect(el: HTMLElement): Rect;
     static deserializeTransform(element: Element): Matrix2D;
     static deserializeTransform(style: CSSStyleDeclaration): Matrix2D;
+    /** Sets the window's vertical scroll position, keeping the current horizontal position. */
     static set scrollTop(y: number);
+    /** Sets the window's horizontal scroll position, keeping the current vertical position. */
     static set scrollLeft(x: number);
+    /**
+     * Scrolls the window to a given position.
+     * @param y Vertical position to scroll to (horizontal position is left unchanged), when only two arguments are supplied.
+     * @param x Horizontal position to scroll to, when `y` is also supplied as a number.
+     * @param smooth Whether to animate the scroll (`true`, default) or jump instantly (`false`).
+     */
+    static scrollTo(y: number, smooth?: boolean): void;
+    static scrollTo(x: number, y: number, smooth?: boolean): void;
+    /** The window's current vertical scroll position, with fallbacks for older browsers. */
     static get scrollTop(): number;
+    /** The window's current horizontal scroll position, with fallbacks for older browsers. */
     static get scrollLeft(): number;
+    /** The window's current viewport size (`{ width, height }`), with fallbacks for older browsers. */
     static get windowSize(): {
         width: number;
         height: number;
@@ -2348,9 +3358,13 @@ export declare class Utils {
     static accelerateCallback(callback: (token: {
         cancel: boolean;
     }) => void, interval?: number, pace?: number, min?: number): void;
+    /** Tests whether `obj` is "empty" (per {@link NullChecker.isEmpty}: `null`/`undefined`/`''`/an empty array or object), excluding DOM `Node`s (which are never considered empty here). */
     static isEmpty(obj: any): boolean;
+    /** Type-guarding test for `obj` being `null` or `undefined`. */
     static isNull(obj: any): obj is null | undefined;
+    /** Type-guarding test for `val` being an array. */
     static isArray(val: any): val is any[];
+    /** Tests whether `val` is `null`/`undefined` or "empty"; see {@link isNull}/{@link isEmpty}. */
     static isNullOrEmpty(val: any): boolean;
     /**
      * It is a `valueOf()` based comparison.
@@ -2365,9 +3379,11 @@ export declare class Utils {
         <T extends {}, U, V, W>(target: T, source1: U, source2: V, source3: W): T & U & V & W;
         (target: object, ...sources: any[]): any;
     };
+    /** Deep-clones `obj`; see {@link DeepCloner}. */
     static clone<T>(obj: T): T;
     /** Legacy alias for Promise.resolve(). */
     static fromResult<T>(v: T): Promise<T>;
+    /** Runs `task` on the next animation frame and wraps its result in a `Promise`. */
     static fromResultAsync<T>(task: () => T): Promise<T>;
     /**
      * Creates an immutable (readonly) copy of an object while preserving the referential values (shallow immutability).
@@ -2383,16 +3399,36 @@ export declare class Utils {
      * @param obj Input array to be frozen
      */
     static readonlyCopy<T>(array: T[]): ReadonlyArray<T>;
+    /** URL/route parsing and formatting helpers, chiefly backing the router (`{segment}`/`{segment?}` template resolution, query-string parsing, route metadata). */
     static URIs: {
+        /**
+         * Substitutes each `{name}`/`{name?}` template segment in `url` with the matching entry of `parameters`
+         * (URL-encoded), then strips out any remaining unmatched *optional* segments.
+         * @param url URL/route template containing `{name}`/`{name?}` segments.
+         * @param parameters Values to substitute, keyed by segment name.
+         * @param removeMatchedParameters When `true`, consumed entries are deleted from `parameters`.
+         */
         format: (url: string, parameters: {
             [name: string]: string;
         }, removeMatchedParameters?: boolean) => string;
+        /**
+         * Appends `parameters` to `url`'s query string (or hash fragment, when `hash` is `true`), URL-encoding
+         * names and values, and correctly choosing `?`/`&` (or `#`/`&`) as the joining separator.
+         * @param url Base URL.
+         * @param parameters Values to append, keyed by parameter name.
+         * @param removeNullEntries When `true`, entries whose value is `null`/`undefined` are omitted instead of appended as empty.
+         * @param hash When `true`, appends to the URL's hash fragment instead of its query string.
+         */
         appendQuery: (url: string, parameters: {
             [name: string]: string;
         }, removeNullEntries?: boolean, hash?: boolean) => string;
+        /** Parses a query string (or a `Location`'s `.search`, defaulting to `window.location`) into a name/value map. */
         parseQuery: (query?: string | Location) => Record<string, string>;
+        /** Tests whether `url` contains at least one non-optional `{name}` template segment (as opposed to only `{name?}` ones). */
         hasMandatoryTemplateSegments: (url: any) => boolean;
+        /** Parses a route template's `{name}`/`{name?}` segments into an ordered list of {@link RouteMetadata} descriptors, consumed by {@link parseState}. */
         parseRoute: (pathTemplate: string) => RouteMetadata[];
+        /** Splits `url` into its `protocol`, `domain`, `path`, `query` (including leading `?`) and `hash` (including leading `#`) parts, or `null` if it can't be parsed. */
         split: (url: string) => {
             protocol?: string;
             domain?: string;
@@ -2400,6 +3436,16 @@ export declare class Utils {
             query?: string;
             hash?: string;
         };
+        /**
+         * Builds a {@link RouterState} for `url`, extracting named route segments per `metadata` (see
+         * {@link parseRoute}) as top-level properties, alongside the standard `$path`/`$pathname`/`$querystring`/
+         * `$query`/`$hash` keys. Throws if a non-optional route segment declared in `metadata` isn't present in `path`.
+         * @param metadata Route segment descriptors, as produced by {@link parseRoute}.
+         * @param url Full URL/path being navigated to.
+         * @param path Path component override; parsed out of `url` via {@link split} when omitted.
+         * @param query Query-string override (including leading `?`); parsed out of `url` when omitted.
+         * @param hash Hash-fragment override (including leading `#`); parsed out of `url` when omitted.
+         */
         parseState: (metadata: RouteMetadata[], url: string, path?: string, query?: string, hash?: string) => RouterState;
     };
     /**
@@ -2408,16 +3454,50 @@ export declare class Utils {
     static getApiResult(json: any): any;
 }
 
+/**
+ * Property decorator that turns a class field into a lazily-resolved, cached reference to a descendant
+ * element matching `selector`. Resolution happens on first read (via `shadowRoot.querySelectorAll` when
+ * available, falling back to the element itself), and only nodes whose `INSTANCE_HOST_VAR` points back
+ * at `this` are considered — this keeps the lookup scoped to the current element's own template output,
+ * skipping over descendants that belong to a nested custom element's own template. The cache is reset
+ * whenever the host element reconnects to the DOM (`connectedCallback`, see the {@link CustomElement} decorator).
+ *
+ * @param selector CSS selector identifying the child element to bind to.
+ * @returns A property decorator to apply to the view-child field (read-only; no setter is defined).
+ */
 export declare function ViewChild(selector: string): (target: any, prop: string, descriptor?: PropertyDescriptor) => void;
 
 declare interface Wai {
     readonly aria: Aria;
 }
 
+/**
+ * Property decorator that turns a plain class field (or accessor) into a Pacem "watched" property:
+ * a property whose changes are detected (via reference/value comparison, see {@link DefaultComparer}),
+ * optionally converted from/to its corresponding attribute string via a {@link PropertyConverter}
+ * (see {@link PropertyConverters}), and notified through `propertyChangedCallback` plus a
+ * {@link PropertyChangeEvent} (unless `config.emit` is `false`).
+ *
+ * Must be paired with the {@link CustomElement} class decorator, which is what actually reads the list
+ * of watched properties (via `WATCH_PROPS_VAR`) to compute `observedAttributes` and wire up attribute/
+ * property change plumbing — `@Watch` alone, on a class not decorated with `@CustomElement`, only sets
+ * up the getter/setter and change notification, with no attribute involvement.
+ *
+ * Array-valued properties are additionally instrumented: their mutating methods (`push`, `pop`, `splice`,
+ * `shift`, `unshift`, `copyWithin`) are patched so in-place mutations also trigger a change notification.
+ *
+ * @param config Optional behavior: `converter` (attribute↔property conversion, default `PropertyConverters.None`),
+ * `emit` (whether to dispatch a {@link PropertyChangeEvent}, default `true`), `debounce` (delay the
+ * change notification, either by a fixed number of milliseconds or `true` for one animation frame),
+ * and `reflectBack` (write the property value back onto the attribute on change, default `false`).
+ * @returns A property decorator to apply to the watched field/accessor.
+ */
 export declare function Watch(config?: WatchConfig): (target: any, prop: string, descriptor?: PropertyDescriptor) => void;
 
+/** Key used to attach, on an element's constructor, the list of its `@Watch`-decorated (watched) property descriptors. */
 export declare const WATCH_PROPS_VAR: string;
 
+/** Configuration options accepted by the {@link Watch} property decorator, controlling conversion, change notification and attribute reflection. */
 export declare type WatchConfig = {
     /** Whether to debounce the property change for a while or not (numeric to specify milliseconds) */
     debounce?: boolean | number;
@@ -2500,6 +3580,11 @@ declare global {
             RegexMatchSegment,
             Repeater,
             RepeaterItem,
+            RouterNavigateEvent,
+            RouterNavigateEventArgs,
+            RouterNavigateEventName,
+            RouterNavigatingEvent,
+            RouterNavigatingEventName,
             RouterState,
             stopPropagationHandler,
             TemplateElement,