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

package/dist/bundle/pacem-core.mjs

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v1.0.0-bernoulli (https://js.pacem.it)
+ * @pacem/pacem-core v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -38,13 +38,20 @@ function assembleEasing(fn, css) {
   return output;
 }
 var Easings = {
+  /** No easing: progress is proportional to elapsed time. */
   linear: assembleEasing(EASINGS.linear, "linear"),
+  /** Sine ease-in: starts slow, accelerates towards the end. */
   sineIn: assembleEasing(EASINGS.sineIn, "cubic-bezier(0.12, 0, 0.39, 0)"),
+  /** Sine ease-out: starts fast, decelerates towards the end. */
   sineOut: assembleEasing(EASINGS.sineOut, "cubic-bezier(0.61, 1, 0.88, 1)"),
+  /** Sine ease-in-out: accelerates then decelerates, symmetric around the midpoint. */
   sineInOut: assembleEasing(EASINGS.sineInOut, "cubic-bezier(0.37, 0, 0.63, 1)"),
   // TODO: set correct pairing
+  /** Exponential ease-in: starts very slow, accelerates sharply towards the end. */
   expoIn: assembleEasing(EASINGS.expoIn, "cubic-bezier(0.7, 0, 0.84, 0)"),
+  /** Exponential ease-out: starts very fast, decelerates sharply towards the end. */
   expoOut: assembleEasing(EASINGS.expoOut, "cubic-bezier(0.16, 1, 0.3, 1)"),
+  /** Exponential ease-in-out: sharp acceleration then sharp deceleration, symmetric around the midpoint. */
   expoInOut: assembleEasing(EASINGS.expoInOut, "cubic-bezier(0.87, 0, 0.13, 1)")
 };
 
@@ -55,6 +62,7 @@ import { Keys as Keys2, Dates, Colors, Strings, Blobs, Imaging, NullChecker, det
 var DeepCloner = class _DeepCloner {
   constructor() {
   }
+  /** Deep-clones `obj`; see {@link DeepCloner} for what gets cloned vs. passed through by reference. */
   static clone(obj2) {
     return new _DeepCloner()._clone(obj2);
   }
@@ -127,9 +135,16 @@ var Json = class _Json {
   constructor(_options) {
     this._options = _options;
   }
+  /**
+   * 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(obj2, options) {
     return new _Json(options)._serialize(obj2);
   }
+  /** Deserializes a string produced by {@link serialize}, restoring references, `RegExp`s, `Element`s and functions. */
   static deserialize(json2) {
     return new _Json()._deserialize(json2);
   }
@@ -240,6 +255,7 @@ var DeferPromise = class _DeferPromise {
       me.deferred = { "resolve": resolve, "reject": reject, "promise": me };
     });
   }
+  /** Standard `PromiseLike.then`, delegating to the underlying native `Promise`. */
   then(onCompleted, onFailed) {
     return this.promise.then(onCompleted, onFailed);
   }
@@ -251,14 +267,17 @@ var DeferPromise = class _DeferPromise {
     this.promise.then(callback, callback);
     return this;
   }
+  /** Registers a fulfillment-only callback (fluent, chainable alternative to `then(callback)`). */
   success(callback) {
     this.promise.then(callback, null);
     return this;
   }
+  /** Registers a rejection-only callback (fluent, chainable alternative to `then(null, callback)`). */
   error(callback) {
     this.promise.then(null, callback);
     return this;
   }
+  /** Creates a new deferred promise and returns its controller: `{ resolve, reject, promise }`. */
   static defer() {
     var q = new _DeferPromise();
     return q.deferred;
@@ -281,27 +300,34 @@ var avoidHandler = (evt) => {
 var SEGMENT_PATTERN = /^\/[^\/]+/;
 var ROUTE_SEGMENT_PATTERN = /\/\{([a-z\$_][\w]*)\??\}/;
 var Utils = 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() {
     const root2 = window["Pacem"];
     var id = root2 && root2.Configuration && root2.Configuration.core || PACEM_CORE_DEFAULT;
     return window[id] = window[id] || {};
   }
+  /** The platform's (native or polyfilled) `customElements` registry. */
   static get customElements() {
     return window["customElements"];
   }
   // #region GENERAL
+  /** Generates a unique numeric-ish id string. */
   static uniqueId() {
     return Keys2.uniqueId();
   }
+  /** Generates a unique short code string. */
   static uniqueCode() {
     return Keys2.uniqueCode();
   }
+  /** Generates a random string of the given `length`. */
   static randomString(length) {
     return Keys2.randomString(length);
   }
+  /** Parses a date-like value (ISO string, `Date`, or timestamp) into a `Date`. */
   static parseDate(input) {
     return Dates.parse(input);
   }
+  /** Writes `input` to the system clipboard, using the async Clipboard API when available and falling back to `document.execCommand('copy')` otherwise. */
   static copyToClipboard(input) {
     if (navigator.clipboard) {
       return navigator.clipboard.writeText(input);
@@ -368,6 +394,7 @@ var Utils = class _Utils {
       return filter;
     }
   }
+  /** Escapes `input` for safe use as a CSS identifier/selector fragment. */
   static cssEscape(input) {
     return escape(input).replace("%", "\\");
   }
@@ -375,9 +402,11 @@ var Utils = class _Utils {
     this.Css = {
       colorize: _Utils.colorize,
       escape: _Utils.cssEscape,
+      /** Reads a CSS custom property's current value off the document root (`:root`/`html`). */
       getVariableValue(name) {
         return getComputedStyle(document.documentElement).getPropertyValue(name);
       },
+      /** Sets a CSS custom property's value on the document root (`:root`/`html`). */
       setVariable(name, value2) {
         getComputedStyle(document.documentElement).setProperty(name, value2);
       },
@@ -405,6 +434,7 @@ var Utils = class _Utils {
         }
         return false;
       },
+      /** Parses an element's (or style declaration's) computed `transform: matrix(...)` CSS value into its 2D affine matrix components; identity if unset. */
       deserializeTransform(element) {
         const style = element instanceof Element ? getComputedStyle(element) : element;
         let a = 1, b = 0, c = 0, d = 1, x = 0, y = 0, matches = /^matrix\((.*)\)$/.exec(style.transform), mij;
@@ -434,6 +464,7 @@ var Utils = class _Utils {
       leftPad: Strings.leftPad,
       format: Strings.format,
       diff: Strings.diff,
+      /** Strips HTML markup from `html`, returning its plain-text content. */
       stripHTML: (html) => {
         let doc = new DOMParser().parseFromString(html, "text/html");
         return doc.body.textContent || "";
@@ -454,6 +485,7 @@ var Utils = class _Utils {
       resize: Imaging.resizeImage
     };
   }
+  /** Loads an image from `src` and resolves with the `HTMLImageElement` once ready (or rejects on error). */
   static loadImage(src) {
     return new Promise((resolve, reject) => {
       const img = new Image();
@@ -470,15 +502,19 @@ var Utils = class _Utils {
       }
     });
   }
+  /** Converts a `Blob` to a `data:` URL string. */
   static blobToDataURL(blob) {
     return _Utils.Blobs.toDataURL(blob);
   }
+  /** Converts a `data:` URL string back into a `Blob`. */
   static dataURLToBlob(dataURL) {
     return _Utils.Blobs.fromDataURL(dataURL);
   }
+  /** Reads a `Blob`'s content as text, using the given `encoding` (default UTF-8). */
   static blobToText(blob, encoding) {
     return _Utils.Blobs.toText(blob, encoding);
   }
+  /** Wraps `content` in a `Blob` of the given MIME `type` (default `'text/plain'`). */
   static textToBlob(content, type = "text/plain") {
     return _Utils.Blobs.fromText(content, type);
   }
@@ -556,6 +592,7 @@ var Utils = class _Utils {
     el.src = url;
     return deferred.promise;
   }
+  /** Returns the list of vendor-prefixed `getUserMedia` implementations available on `navigator`, if any. */
   static getUserMediaFunctions() {
     var _getUserMedia = [];
     let methods = [navigator["getUserMedia"], navigator["webkitGetUserMedia"], navigator["msGetUserMedia"], navigator["mozGetUserMedia"]];
@@ -773,12 +810,14 @@ var Utils = class _Utils {
   }
   // #endregion
   // #region DOM
+  /** Whether the document (including module scripts) has fully finished loading (`document.readyState === 'complete'`). */
   static isDOMReady() {
     return (
       /* document.readyState === 'interactive' ||*/
       document.readyState === "complete"
     );
   }
+  /** Registers `listener` to run once the document (and its resources, e.g. images) has fully loaded (the `window` `'load'` event). */
   static onDOMReady(listener) {
     window.addEventListener("load", listener, false);
   }
@@ -805,12 +844,15 @@ var Utils = class _Utils {
     }
     return dom;
   }
+  /** Cross-browser `Element.matches(selector)`, falling back to vendor-prefixed variants. */
   static is(el, selector) {
     return (el.matches || el.matchesSelector || el.msMatchesSelector || el.mozMatchesSelector || el.webkitMatchesSelector || el.oMatchesSelector).call(el, selector);
   }
+  /** Resolves the effective language for `el`: its own `lang` attribute, else the document's, else the browser's. */
   static lang(el) {
     return el.lang || document.documentElement.lang || navigator.language;
   }
+  /** JSON-stringifies `obj` (via {@link Json}), or passes through `null`/`undefined` unchanged. */
   static jsonSortStringify(obj2) {
     if (_Utils.isNull(obj2)) {
       return obj2;
@@ -822,6 +864,7 @@ var Utils = class _Utils {
       detect
     };
   }
+  /** Parses a `document.cookie`-style string (or `document.cookie` itself, by default) into a name/value map. */
   static cookies(cookie) {
     const cookies = (cookie ?? document.cookie).split(";"), retval = {};
     for (var pair of cookies) {
@@ -841,6 +884,7 @@ var Utils = class _Utils {
   }
   static {
     this.Cookies = {
+      /** Retrieves all cookies (or just `cookieName`, if given) as {@link CookieData} entries. */
       getAll: async (cookieName) => {
         const store = "cookieStore" in window ? window.cookieStore : null;
         const retval = [];
@@ -857,6 +901,7 @@ var Utils = class _Utils {
           return await store.getAll(cookieName);
         }
       },
+      /** 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) => {
         let retval = `${data.name}=${encodeURIComponent(data.value ?? "")}`;
         if (!_Utils.isNullOrEmpty(data.domain)) {
@@ -884,6 +929,7 @@ var Utils = class _Utils {
       }
     };
   }
+  /** Tests whether `el` is currently visible (via the `checkVisibility` API when available, falling back to a CSS-visibility/size heuristic). */
   static isVisible(el) {
     if ("checkVisibility" in el) {
       return el.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true });
@@ -891,6 +937,7 @@ var Utils = class _Utils {
     return getComputedStyle(el).visibility !== "hidden" && (el.clientWidth > 0 || el.clientHeight > 0);
   }
   //#region classList DOMTokenList (css)
+  /** Tests whether `el` has `className` set, using `classList` when available (with a regex-based fallback). */
   static hasClass(el, className) {
     if (el.classList) {
       return el.classList.contains(className);
@@ -898,6 +945,7 @@ var Utils = class _Utils {
       return new RegExp("(^| )" + className + "( |$)", "gi").test(el.className);
     }
   }
+  /** Adds one or more (space-separated) classes to `el`, using `classList` when available. */
   static addClass(el, className) {
     const css = className.trim();
     if (el.classList) {
@@ -906,6 +954,7 @@ var Utils = class _Utils {
       el.setAttribute("class", el.className + " " + css);
     }
   }
+  /** Removes one or more (space-separated) classes from `el`, using `classList` when available. */
   static removeClass(el, className) {
     const css = className.trim();
     if (el.classList) {
@@ -914,6 +963,7 @@ var Utils = class _Utils {
       el.setAttribute("class", el.className.replace(new RegExp("(^|\\b)" + css.split(" ").join("|") + "(\\b|$)", "gi"), " "));
     }
   }
+  /** Adds or removes `className` on `el` depending on `on`; see {@link addClass}/{@link removeClass}. */
   static toggleClass(el, className, on) {
     if (on) {
       _Utils.addClass(el, className);
@@ -923,15 +973,19 @@ var Utils = class _Utils {
   }
   //#endregion
   //#region part DOMTokenList (shadow-DOM)
+  /** Tests whether `el`'s `part` attribute (CSS Shadow Parts) contains `partName`. */
   static hasPart(el, partName) {
     return el.part.contains(partName);
   }
+  /** Adds one or more (space-separated) shadow-part names to `el`'s `part` attribute. */
   static addPart(el, partName) {
     DOMTokenList.prototype.add.apply(el.part, partName.trim().split(" "));
   }
+  /** Removes one or more (space-separated) shadow-part names from `el`'s `part` attribute. */
   static removePart(el, partName) {
     DOMTokenList.prototype.remove.apply(el.part, partName.trim().split(" "));
   }
+  /** Adds or removes `partName` on `el`'s `part` attribute depending on `on`; see {@link addPart}/{@link removePart}. */
   static togglePart(el, partName, on) {
     if (on) {
       _Utils.addPart(el, partName);
@@ -966,9 +1020,11 @@ var Utils = class _Utils {
       height: rect.height
     };
   }
+  /** 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) {
     return (el?.offsetTop ?? 0) + (el?.offsetParent && el.offsetParent instanceof HTMLElement ? this.naturalOffsetTop(el.offsetParent) : 0);
   }
+  /** 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) {
     return (el?.offsetTop ?? 0) + (el?.offsetParent && el.offsetParent instanceof HTMLElement ? this.naturalOffsetLeft(el.offsetParent) : 0);
   }
@@ -996,18 +1052,30 @@ var Utils = class _Utils {
   static deserializeTransform(obj2) {
     return _Utils.Css.deserializeTransform(obj2);
   }
+  /** Sets the window's vertical scroll position, keeping the current horizontal position. */
   static set scrollTop(y) {
     window.scrollTo(_Utils.scrollLeft, y);
   }
+  /** Sets the window's horizontal scroll position, keeping the current vertical position. */
   static set scrollLeft(x) {
     window.scrollTo(x, _Utils.scrollTop);
   }
+  static scrollTo(x, y = true, smooth = true) {
+    const yFirst = _Utils.isNull(y) || typeof y === "boolean";
+    const left = yFirst ? _Utils.scrollLeft : x;
+    const top = yFirst ? x : y;
+    const behavior = (yFirst ? y : smooth) ? "smooth" : "instant";
+    window.scrollTo({ behavior, left, top });
+  }
+  /** The window's current vertical scroll position, with fallbacks for older browsers. */
   static get scrollTop() {
     return window.scrollY || document.documentElement.scrollTop || document.body.scrollTop || 0;
   }
+  /** The window's current horizontal scroll position, with fallbacks for older browsers. */
   static get scrollLeft() {
     return window.scrollX || document.documentElement.scrollLeft || document.body.scrollLeft || 0;
   }
+  /** The window's current viewport size (`{ width, height }`), with fallbacks for older browsers. */
   static get windowSize() {
     let win = window;
     return {
@@ -1081,16 +1149,20 @@ var Utils = class _Utils {
   }
   // #endregion
   // #region other
+  /** 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(obj2) {
     return NullChecker.isEmpty(obj2) && !(obj2 instanceof Node);
   }
+  /** Type-guarding test for `obj` being `null` or `undefined`. */
   static isNull(obj2) {
     return NullChecker.isNull(obj2);
   }
   // legacy
+  /** Type-guarding test for `val` being an array. */
   static isArray(val) {
     return Array.isArray(val);
   }
+  /** Tests whether `val` is `null`/`undefined` or "empty"; see {@link isNull}/{@link isEmpty}. */
   static isNullOrEmpty(val) {
     return _Utils.isNull(val) || _Utils.isEmpty(val);
   }
@@ -1109,6 +1181,7 @@ var Utils = class _Utils {
   static {
     this.extend = Object.assign;
   }
+  /** Deep-clones `obj`; see {@link DeepCloner}. */
   static clone(obj2) {
     if (obj2 === void 0)
       return void 0;
@@ -1118,6 +1191,7 @@ var Utils = class _Utils {
   static fromResult(v) {
     return Promise.resolve(v);
   }
+  /** Runs `task` on the next animation frame and wraps its result in a `Promise`. */
   static fromResultAsync(task) {
     return new Promise((resolve) => requestAnimationFrame(() => resolve(task())));
   }
@@ -1140,6 +1214,13 @@ var Utils = class _Utils {
   }
   static {
     this.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: function(url, parameters, removeMatchedParameters) {
         for (let name in parameters || {}) {
           let tmpl = new RegExp("(^|\\/)\\{" + name + "\\??\\}(\\/|$)");
@@ -1160,11 +1241,20 @@ var Utils = class _Utils {
         }
         return url;
       },
+      /**
+       * 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: function(url, parameters, removeNullEntries = false, hash = false) {
         const char = hash ? "#" : "?", pattern = hash ? /#/ : /\?/;
         const query = (pattern.test(url) ? "&" : char) + Object.keys(parameters).filter((k) => !_Utils.isNull(parameters[k]) || !removeNullEntries).map((k) => encodeURIComponent(k) + "=" + encodeURIComponent(parameters[k] ?? "")).join("&");
         return url + (query.length > 1 ? query : "");
       },
+      /** Parses a query string (or a `Location`'s `.search`, defaulting to `window.location`) into a name/value map. */
       parseQuery: (query = window.location) => {
         if (typeof query !== "string") {
           query = query.search;
@@ -1175,9 +1265,11 @@ var Utils = class _Utils {
         });
         return obj2;
       },
+      /** Tests whether `url` contains at least one non-optional `{name}` template segment (as opposed to only `{name?}` ones). */
       hasMandatoryTemplateSegments: function(url) {
         return /(^|\/)\{\.*\}(\/|$)/.test(url);
       },
+      /** Parses a route template's `{name}`/`{name?}` segments into an ordered list of {@link RouteMetadata} descriptors, consumed by {@link parseState}. */
       parseRoute: function(pathTemplate) {
         let tmpl = pathTemplate;
         const trunks = [];
@@ -1197,6 +1289,7 @@ var Utils = class _Utils {
         }
         return trunks;
       },
+      /** Splits `url` into its `protocol`, `domain`, `path`, `query` (including leading `?`) and `hash` (including leading `#`) parts, or `null` if it can't be parsed. */
       split: function(url) {
         const URL_PATTERN = /^((https?:)?\/\/[^\/]+)?([^\?#]+)(\?[^#]*)?(#[^#]*)?$/;
         const regArr = URL_PATTERN.exec(url);
@@ -1205,6 +1298,16 @@ var Utils = class _Utils {
         }
         return { domain: regArr[2] ?? "", protocol: regArr[1] ?? "", path: regArr[3] ?? "", query: regArr[4] ?? "", hash: regArr[5] ?? "" };
       },
+      /**
+       * 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: function(metadata, url, path, query, hash) {
         let fullPath = url;
         if (_Utils.isNullOrEmpty(path)) {
@@ -1295,9 +1398,21 @@ var EventKeyModifier;
   EventKeyModifier2["MetaKey"] = "Cmd";
 })(EventKeyModifier || (EventKeyModifier = {}));
 var CustomEventUtils = class {
+  /**
+   * 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(evt, type) {
     return evt instanceof type;
   }
+  /**
+   * 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) {
     var src;
     if ("touches" in evt) {
@@ -1315,6 +1430,11 @@ var CustomEventUtils = class {
       client: { x: src.clientX, y: src.clientY }
     };
   }
+  /**
+   * 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) {
     var which = evt.which;
     if (evt instanceof MouseEvent) {
@@ -1336,6 +1456,13 @@ var CustomEventUtils = class {
     }
     return true;
   }
+  /**
+   * 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(evt, type) {
     if (!(evt instanceof type)) {
       Object.setPrototypeOf(evt, type);
@@ -1345,6 +1472,11 @@ var CustomEventUtils = class {
 
 // packages/core/dist/esm/events.js
 var CustomTypedEvent = class extends CustomEvent {
+  /**
+   * @param type Event name.
+   * @param detail Strongly-typed payload, exposed as `event.detail`.
+   * @param eventInit Standard `CustomEvent` initialization options (`bubbles`, `cancelable`, `composed`).
+   */
   constructor(type, detail, eventInit) {
     super(type, Utils.extend({ detail }, eventInit || {}));
     CustomEventUtils.fixEdgeCustomEventSubClassInstance(this, this.constructor);
@@ -1362,6 +1494,12 @@ function isEventInit(obj2) {
   return false;
 }
 var CustomUIEvent = class extends CustomEvent {
+  /**
+   * @param type Event name.
+   * @param detail Either the strongly-typed payload, or (when it satisfies `CustomEventInit`, i.e. has a `detail` key) the full event-init object.
+   * @param eventInit Either standard `CustomEvent` init options, or the original native event this custom event derives from (in which case its coordinates/modifiers get captured).
+   * @param orig The original native mouse/touch/keyboard event this custom event derives from, when `eventInit` is itself the init options.
+   */
   constructor(type, detail, eventInit, orig) {
     super(type, Utils.extend(isEventInit(detail || {}) ? detail : { detail }, !(eventInit instanceof Event) && eventInit || {}));
     const originalEvent = orig || eventInit;
@@ -1426,6 +1564,20 @@ var PropertyChangeEvent = class extends CustomTypedEvent {
     super(PropertyChangeEventName, args);
   }
 };
+var RouterNavigatingEventName = "navigating";
+var RouterNavigateEventName = "navigate";
+var RouterNavigateEvent = class extends CustomTypedEvent {
+  /** @param path Either the destination path alone, or the full navigation args (path, title, referrer). */
+  constructor(path) {
+    super(RouterNavigateEventName, typeof path === "string" ? { path } : path, { cancelable: false, bubbles: false });
+  }
+};
+var RouterNavigatingEvent = class extends CustomTypedEvent {
+  /** @param path Destination path about to be navigated to. */
+  constructor(path) {
+    super(RouterNavigatingEventName, path, { cancelable: true, bubbles: false });
+  }
+};
 
 // packages/core/dist/esm/animations/events.js
 var AnimationEvent = class extends CustomTypedEvent {
@@ -1446,6 +1598,16 @@ var AnimationStartEvent = class extends CustomEvent {
 
 // packages/core/dist/esm/animations/tween-service.js
 var TweenService = class {
+  /**
+   * 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, to, duration, delay = 0, easing = Easings.linear, callback = null) {
     return new Promise((resolve, _) => {
       const now = performance && performance.now() || Date.now();
@@ -1495,9 +1657,15 @@ var Timer = class _Timer {
     this.#handle = requestAnimationFrame(this._run);
   }
   #then;
+  /**
+   * 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, fps = 60) {
     return new _Timer(callback, fps);
   }
+  /** Stops the timer, cancelling any pending animation frame. */
   stop() {
     cancelAnimationFrame(this.#handle);
   }
@@ -1533,6 +1701,7 @@ var FetchResultEventName = "fetchresult";
 var FetchErrorEventName = "error";
 var FetchSuccessEventName = "success";
 var Fetcher = class {
+  /** Tests whether a response carries no body (HTTP 204, or an explicit `Content-Length: 0`). */
   static isEmpty(r) {
     return r.status === 204 || r.headers.get("Content-Length") === "0";
   }
@@ -1542,15 +1711,18 @@ var Fetcher = class {
 var noop = () => {
 };
 var StatusCodeError = class extends Error {
+  /** @param statusCode HTTP status code (`500` for network-level failures). @param statusText Status text / error message. */
   constructor(statusCode, statusText) {
     super(statusText);
     this.statusCode = statusCode;
   }
+  /** The HTTP status code that caused this error. */
   get status() {
     return this.statusCode;
   }
 };
 var Response = class {
+  /** @param req The completed `XMLHttpRequest`. @param processTime Elapsed request time, in milliseconds. */
   constructor(req, processTime) {
     if (!req)
       return;
@@ -1561,20 +1733,25 @@ var Response = class {
     this._allHeadersRaw = req.getAllResponseHeaders();
     this._processTime = processTime;
   }
+  /** Elapsed request time, in milliseconds. */
   get processTime() {
     return this._processTime;
   }
+  /** Response headers, parsed into a name/value map (lazily, on first access). */
   get headers() {
     if (this._headers === void 0 && this._allHeadersRaw)
       this._parseHeaders();
     return this._headers;
   }
+  /** The `Content-Length` response header, parsed as a number. */
   get size() {
     return +this.headers["Content-Length"];
   }
+  /** The `Content-Type` response header. */
   get mime() {
     return this.headers["Content-Type"];
   }
+  /** The `Date` response header, parsed into a `Date`. */
   get date() {
     return new Date(Date.parse(this.headers["Date"]));
   }
@@ -1590,15 +1767,19 @@ var Response = class {
     });
     this._headers = headers;
   }
+  /** HTTP status code. */
   get status() {
     return this._status;
   }
+  /** Raw response body as text. */
   get text() {
     return this._text;
   }
+  /** Response body, typed per `XMLHttpRequest.responseType` (see {@link type}). */
   get content() {
     return this._body;
   }
+  /** The `XMLHttpRequest.responseType` used for this request. */
   get type() {
     return this._type;
   }
@@ -1786,6 +1967,7 @@ var DragDropInitEventArgsClass = class _DragDropInitEventArgsClass extends DragD
     this.placeholder = _builder.placeholder;
     this.data = _builder.data;
   }
+  /** Builds a new {@link DragDropInitEventArgsClass} out of a plain {@link DragDropEventArgs} builder. */
   static fromArgs(builder) {
     return new _DragDropInitEventArgsClass(Utils.extend({}, builder));
   }
@@ -1796,12 +1978,15 @@ var DragDropEventArgsClass = class _DragDropEventArgsClass extends DragDropEvent
     this._placeholder = _placeholder;
     this._data = _data;
   }
+  /** @readonly Gets the element used as a dragging placeholder. */
   get placeholder() {
     return this._placeholder;
   }
+  /** @readonly Gets the logical payload being dragged. */
   get data() {
     return this._data;
   }
+  /** Builds a new {@link DragDropEventArgsClass} out of a plain {@link DragDropEventArgs} builder. */
   static fromArgs(builder) {
     return new _DragDropEventArgsClass(Utils.extend({}, builder));
   }
@@ -1831,18 +2016,23 @@ var RescaleEventArgsClass = class _RescaleEventArgsClass {
   constructor(_builder) {
     this._builder = _builder;
   }
+  /** @readonly Gets the current pointer position. */
   get currentPosition() {
     return this._builder.currentPosition;
   }
+  /** @readonly Gets the rectangle the element is being resized to. */
   get targetRect() {
     return this._builder.targetRect;
   }
+  /** @readonly Gets the element being resized. */
   get element() {
     return this._builder.element;
   }
+  /** @readonly Gets the handle being dragged (see {@link RescaleHandle}). */
   get handle() {
     return this._builder.handle;
   }
+  /** Builds a new {@link RescaleEventArgsClass} out of a plain {@link RescaleEventArgs} builder. */
   static fromArgs(builder) {
     return new _RescaleEventArgsClass(Utils.extend({}, builder));
   }
@@ -1864,18 +2054,23 @@ var RotateEventArgsClass = class _RotateEventArgsClass {
   constructor(_builder) {
     this._builder = _builder;
   }
+  /** @readonly Gets the current pointer position. */
   get currentPosition() {
     return this._builder.currentPosition;
   }
+  /** @readonly Gets the current rotation, in radians. */
   get rotation() {
     return this._builder.rotation;
   }
+  /** @readonly Gets the element being rotated. */
   get element() {
     return this._builder.element;
   }
+  /** @readonly Gets the pivot point the element is rotating around. */
   get center() {
     return this._builder.center;
   }
+  /** Builds a new {@link RotateEventArgsClass} out of a plain {@link RotateEventArgs} builder. */
   static fromArgs(builder) {
     return new _RotateEventArgsClass(Utils.extend({}, builder));
   }
@@ -1910,6 +2105,7 @@ var SwipeEventArgsClass = class _SwipeEventArgsClass {
     const isVertical = vertical ?? Math.abs(horizontalspeed) < Math.abs(verticalspeed);
     return isVertical;
   }
+  /** @readonly Gets the resolved swipe direction (`'up'`, `'down'`, `'left'` or `'right'`). */
   get direction() {
     return this.#isVertical ? this._builder.verticalspeed > 0 ? "down" : "up" : this._builder.horizontalspeed > 0 ? "right" : "left";
   }
@@ -1940,9 +2136,11 @@ var SwipeEventArgsClass = class _SwipeEventArgsClass {
       /* v/v0 where v ~ 0 <=> 1% of v0 */
     ) / inertia;
   }
+  /** @readonly Gets the element being swiped. */
   get element() {
     return this._builder.element;
   }
+  /** Builds a new {@link SwipeEventArgsClass} out of a plain {@link SwipeEventArgs} builder. */
   static fromArgs(builder) {
     return new _SwipeEventArgsClass(Utils.extend({}, builder));
   }
@@ -2025,10 +2223,6 @@ __export(index_components_exports, {
   RepeaterItemRemoveEventName: () => RepeaterItemRemoveEventName,
   ResizeEvent: () => ResizeEvent,
   ResizeEventName: () => ResizeEventName,
-  RouterNavigateEvent: () => RouterNavigateEvent,
-  RouterNavigateEventName: () => RouterNavigateEventName,
-  RouterNavigatingEvent: () => RouterNavigatingEvent,
-  RouterNavigatingEventName: () => RouterNavigatingEventName,
   ScrollEvent: () => ScrollEvent,
   ScrollEventName: () => ScrollEventName,
   StateEvent: () => StateEvent,
@@ -2063,17 +2257,40 @@ var TemplateElement = class extends HTMLElement {
 var PACEM_BAG = "__pacem__";
 var bindingPattern = /^\{\{(.|\n)+\}\}$/;
 var CustomElementUtils = class _CustomElementUtils {
+  /** `true` when the platform's `customElements` registry is the Custom Elements polyfill rather than a native implementation. */
   static get polyfilling() {
     return customElements instanceof window["CustomElementRegistry"];
   }
+  /** Converts a camelCase property name to its kebab-case attribute-name equivalent (e.g. `myProp` → `my-prop`). */
   static camelToKebab(camelCased) {
     return camelCased && camelCased.replace(/([A-Z])/g, "-$1").toLowerCase();
   }
+  /** Converts a kebab-case attribute name to its camelCase property-name equivalent (e.g. `my-prop` → `myProp`). */
   static kebabToCamel(kebabCased) {
     return kebabCased && kebabCased.replace(/(-[a-z])/g, (m) => {
       return m[1].toUpperCase();
     });
   }
+  /** Waits for the specified alement to be ready. */
+  static waitForReady(element) {
+    return new Promise((resolve, reject) => {
+      if (Utils.isNull(element)) {
+        reject("Not found.");
+      }
+      if (element.isReady) {
+        resolve();
+      }
+      const callback = () => {
+        element.removeEventListener("load", callback);
+        resolve();
+      };
+      element.addEventListener("load", callback);
+    });
+  }
+  /** Waits for the specified element to be ready, then executes the provided callback. */
+  static whenReady(element, callback) {
+    _CustomElementUtils.waitForReady(element).then(callback);
+  }
   static getWatchedProperties(target, includeInherited = true) {
     var properties = [];
     var chain = target instanceof HTMLElement ? target.constructor : target;
@@ -2084,9 +2301,16 @@ var CustomElementUtils = class _CustomElementUtils {
     } while (includeInherited && (chain = Object.getPrototypeOf(chain)));
     return properties;
   }
+  /** Retrieves a single `@Watch`-decorated property descriptor by name; see {@link getWatchedProperties}. */
   static getWatchedProperty(target, name) {
     return this.getWatchedProperties(target, true).find((p) => p.name === name);
   }
+  /**
+   * 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, integrity = null, crossorigin = false) {
     var attrs = { "type": "text/javascript", "src": src };
     if (!Utils.isNullOrEmpty(integrity))
@@ -2095,6 +2319,12 @@ var CustomElementUtils = class _CustomElementUtils {
       Utils.extend(attrs, { "crossorigin": "" });
     return _CustomElementUtils.import(src, "script", attrs, document.head || document.getElementsByTagName("head")[0]);
   }
+  /**
+   * 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, integrity = null, crossorigin = false) {
     var attrs = { "rel": "stylesheet", "href": src };
     if (!Utils.isNullOrEmpty(integrity))
@@ -2103,6 +2333,15 @@ var CustomElementUtils = class _CustomElementUtils {
       Utils.extend(attrs, { "crossorigin": "anonymous" });
     return _CustomElementUtils.import(src, "link", attrs, document.head || document.getElementsByTagName("head")[0]);
   }
+  /**
+   * 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(key2, tagName, attrs, appendTo = document.body) {
     const _p = Utils.core;
     var _imports = _p["imports"] = _p["imports"] || {};
@@ -2131,6 +2370,7 @@ var CustomElementUtils = class _CustomElementUtils {
   }
   static {
     this.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() {
         function cleanupQuotes(input) {
           if (/^('|").*\1$/.test(input)) {
@@ -2165,6 +2405,14 @@ var CustomElementUtils = class _CustomElementUtils {
       }
     };
   }
+  /**
+   * 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, name, value2) {
     if (Utils.isNull(target))
       return;
@@ -2180,9 +2428,16 @@ var CustomElementUtils = class _CustomElementUtils {
     else
       bag[name] = value2;
   }
+  /** Removes a value previously stored via {@link setAttachedPropertyValue}. */
   static deleteAttachedPropertyValue(target, name) {
     _CustomElementUtils.setAttachedPropertyValue(target, name, void 0);
   }
+  /**
+   * 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, name, ensureValue) {
     const propKey = Object.getOwnPropertyDescriptor(target, PACEM_BAG), bag = propKey && propKey.value;
     if (Utils.isNull(bag && bag[name]) && !Utils.isNull(ensureValue)) {
@@ -2227,6 +2482,17 @@ var CustomElementUtils = class _CustomElementUtils {
     }
     return { target: { value: ref, name }, parent: { value: parent || scope, path: path.substring(0, ndx) }, root: { value: root2, property: core } };
   }
+  /**
+   * 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, path, value2) {
     var obj2 = _CustomElementUtils.resolvePath(path, element);
     var current = obj2.target.value;
@@ -2246,6 +2512,7 @@ var CustomElementUtils = class _CustomElementUtils {
       }
     }
   }
+  /** Reads the value at the given dotted `path`, rooted at `element`; see {@link resolvePath}. */
   static get(element, path) {
     var obj2 = _CustomElementUtils.resolvePath(path, element);
     return obj2 && obj2.target && obj2.target.value;
@@ -2262,11 +2529,26 @@ var CustomElementUtils = class _CustomElementUtils {
     } while (el != null && (el != (retval = element.ownerDocument) || el instanceof HTMLElement && (retval = el.shadowRoot) != null));
     return retval;
   }
+  /**
+   * 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) {
     let retval = element.isConnected ? element.getRootNode() : _CustomElementUtils.getAttachedPropertyValue(element, INSTANCE_SCOPE_VAR);
     return retval ?? /* in Jasmine TESTS `element.isConnected` always returns false (attached to #document-fragment) */
     _CustomElementUtils._findScopeContextLegacy(element);
   }
+  /**
+   * 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, predicate) {
     let el = element;
     let retval;
@@ -2280,12 +2562,20 @@ var CustomElementUtils = class _CustomElementUtils {
     }
     return retval;
   }
+  /** Finds the nearest ancestor "shell" element - matching `.{@link PCSS}-body` - or falls back to `document.body`; see {@link findAncestor}. */
   static findAncestorShell(element) {
     return _CustomElementUtils.findAncestor(element, (el) => Utils.is(el, `.${PCSS}-body`) || el === document.body);
   }
+  /** Finds the nearest ancestor that is an instance of `ctor`; see {@link findAncestor}. */
   static findAncestorOfType(element, ctor) {
     return _CustomElementUtils.findAncestor(element, (el) => el instanceof ctor);
   }
+  /**
+   * 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, predicate, firstOnly = false) {
     const walker = document.createTreeWalker(element, NodeFilter.SHOW_ELEMENT);
     var retval = [];
@@ -2300,10 +2590,16 @@ var CustomElementUtils = class _CustomElementUtils {
     }
     return retval;
   }
+  /** Finds the first descendant of `element` matching `predicate`, or `undefined` if none matches; see {@link findDescendants}. */
   static findFirstDescendant(element, predicate) {
     const any = _CustomElementUtils.findDescendants(element, predicate, true);
     return Utils.isNullOrEmpty(any) ? void 0 : any[0];
   }
+  /**
+   * 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(selector = "[pacem]", filter = (e) => true) {
     const retval = [];
     document.querySelectorAll(selector).forEach((e, i, arr2) => {
@@ -2363,6 +2659,14 @@ var CustomElementUtils = class _CustomElementUtils {
     } while (el != null);
     return retval;
   }
+  /**
+   * 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, template) {
     const walker = document.createTreeWalker(template.content, NodeFilter.SHOW_ELEMENT + /* traverse templates' content */
     NodeFilter.SHOW_DOCUMENT_FRAGMENT);
@@ -2373,6 +2677,13 @@ var CustomElementUtils = class _CustomElementUtils {
       }
     }
   }
+  /**
+   * 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) {
     let el = element;
     let retval;
@@ -2390,9 +2701,11 @@ var CustomElementUtils = class _CustomElementUtils {
       logFn(`Element "${element.constructor.name}" isn't a descendant of a templated component.`);
     return retval;
   }
+  /** Tests whether an attribute's raw string value has binding-expression syntax (`{{ ... }}`). */
   static isBindingAttribute(attr) {
     return bindingPattern.test(attr);
   }
+  /** 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) {
     if (_CustomElementUtils.isBindingAttribute(attr)) {
       return attr.substr(2, attr.length - 4);
@@ -2400,6 +2713,13 @@ var CustomElementUtils = class _CustomElementUtils {
       throw `Invalid attribute: incorrect binding syntax.`;
     }
   }
+  /**
+   * 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, element) {
     let expression = _CustomElementUtils.extractBindingAttributeExpression(attr);
     const arr2 = /,\s*(twoway|once)\s*$/.exec(expression), mode = arr2 && arr2.length > 1 && arr2[1];
@@ -2419,6 +2739,14 @@ var CustomElementUtils = class _CustomElementUtils {
     });
     return expr;
   }
+  /**
+   * 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, name, attributes) {
     let original = Object.getOwnPropertyDescriptor(o, name);
     if (original != void 0)
@@ -2493,6 +2821,15 @@ var Repeater = class {
   }
 };
 var RepeaterItem = class _RepeaterItem {
+  /**
+   * 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, upLevels = 0, logFn = console.warn) {
     if (Utils.isNull(element) || element.localName === "template" || element instanceof /* template-like element? */
     TemplateElement) {
@@ -2506,16 +2843,20 @@ var RepeaterItem = class _RepeaterItem {
     }
     return item;
   }
+  /** Tests whether `node` is the placeholder of some {@link RepeaterItem}. */
   static isRepeaterItem(node) {
     return !Utils.isNull(GET_VAL(node, REPEATERITEM_PLACEHOLDER));
   }
+  /** Retrieves the {@link RepeaterItem} attached to `node`, if `node` is a repeater-item placeholder; see {@link isRepeaterItem}. */
   static getRepeaterItem(node) {
     return GET_VAL(node, REPEATERITEM_PLACEHOLDER);
   }
+  /** @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) {
     this._placeholder = _placeholder;
     SET_VAL(_placeholder, REPEATERITEM_PLACEHOLDER, this);
   }
+  /** The DOM placeholder node standing in for this repetition. */
   get placeholder() {
     return this._placeholder;
   }
@@ -2531,27 +2872,38 @@ var Expression = class _Expression {
     this._pending = false;
     this._independent = false;
   }
+  /** The resolved property dependencies (element + property + path) this expression re-evaluates on change. Empty for {@link independent} expressions. */
   get dependencies() {
     return this._dependencies;
   }
+  /** The compiled function body used by {@link evaluate}/{@link evaluateAsync} (a `return <expr>;` statement, guarded by a try/catch). */
   get functionBody() {
     return this._fnBody;
   }
+  /** 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() {
     return this._voidBody;
   }
+  /**
+   * `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() {
     return this._pending;
   }
+  /** `true` when the expression has no dependencies (a constant) and can be evaluated immediately, without a resolved scope. */
   get independent() {
     return this._independent;
   }
+  /** Evaluates the expression and returns its result, swallowing any runtime error (returning `undefined`). */
   evaluate() {
     if (!this._fn) {
       this._fn = new Function("$pacem", CONTEXT_PREFIX, this._fnBody);
     }
     return this._fn.apply(null, [Utils.core, this._args]);
   }
+  /** Promise-wrapped variant of {@link evaluate} (resolves synchronously with the same result - kept for call-site uniformity with genuinely async evaluation paths). */
   evaluateAsync() {
     const deferred = DeferPromise.defer();
     if (!this._fn) {
@@ -2560,6 +2912,12 @@ var Expression = class _Expression {
     deferred.resolve(this._fn.apply(null, [Utils.core, this._args]));
     return deferred.promise;
   }
+  /**
+   * 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 = {}) {
     if (!this._fn) {
       let argNames = [CONTEXT_PREFIX];
@@ -2586,6 +2944,15 @@ var Expression = class _Expression {
     }
     return _Expression._pendingExpression;
   }
+  /**
+   * 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, element) {
     var context = CustomElementUtils.findScopeContext(element);
     var args = { "$this": element };
@@ -3973,6 +4340,10 @@ var PacemAdapter = class extends PacemElement {
     const current = this._getAvailable();
     return ndx === this._getNextAvailable(current);
   }
+  /**
+   * Sets the master's index to the closest available item to the provided one.
+   * @param ndx Desired index
+   */
   select(ndx) {
     this._element.index = this._getAvailable(ndx);
   }
@@ -4096,6 +4467,10 @@ var PacemBroadcastChannelProxyElement = class PacemBroadcastChannelProxyElement2
     this._disposeChannel();
     super.disconnectedCallback();
   }
+  /**
+   * Posts a message through the channel.
+   * @param message Message to send; defaults to the current `message` property
+   */
   send(message = this.message) {
     if (this.disabled) {
       return;
@@ -4161,9 +4536,11 @@ var PacemBrowserDetectElement = class PacemBrowserDetectElement2 extends PacemEv
   }
   #browser;
   #version;
+  /** @readonly Gets the detected browser name. */
   get browser() {
     return this.#browser;
   }
+  /** @readonly Gets the detected browser version. */
   get version() {
     return this.#version;
   }
@@ -4221,15 +4598,22 @@ var Storage = class {
     storage = this._getStorage(!persistent);
     storage.removeItem(name);
   }
+  /**
+   * 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) {
     return this._parseValue(this._getStorage(false), name) || this._parseValue(this._getStorage(true), name);
   }
+  /** Clears both session and local storage entirely. */
   clear() {
     var storage = this._getStorage(true);
     storage.clear();
     storage = this._getStorage(false);
     storage.clear();
   }
+  /** Removes a single entry by `name` from both session and local storage. */
   removeProperty(name) {
     var storage = this._getStorage(true);
     storage.removeItem(name);
@@ -4882,6 +5266,7 @@ var PacemHistoryElement = class PacemHistoryElement2 extends PacemEventTarget {
       this.#history = new HistoryService(val, this.maxlength);
     }
   }
+  /** Moves the state forward one step, if `canRedo` is `true`. */
   redo() {
     const h = this.#history;
     if (!Utils.isNull(h)) {
@@ -4890,6 +5275,7 @@ var PacemHistoryElement = class PacemHistoryElement2 extends PacemEventTarget {
       this._synchronize("redo");
     }
   }
+  /** Clears the history stack, keeping only the current state. */
   reset() {
     const h = this.#history;
     if (!Utils.isNull(h)) {
@@ -4898,6 +5284,7 @@ var PacemHistoryElement = class PacemHistoryElement2 extends PacemEventTarget {
       this._synchronize("reset");
     }
   }
+  /** Moves the state back one step, if `canUndo` is `true`. */
   undo() {
     const h = this.#history;
     if (!Utils.isNull(h)) {
@@ -5445,6 +5832,7 @@ var PacemRepeaterElement = PacemRepeaterElement_1 = class PacemRepeaterElement2
       this._databind();
     };
   }
+  /** Removes the rendered item at the given index. */
   removeItem(index) {
     this._removeItems(index, index);
   }
@@ -5472,6 +5860,7 @@ var PacemRepeaterElement = PacemRepeaterElement_1 = class PacemRepeaterElement2
       item.remove();
     }
   }
+  /** Forces a full re-render of the items against the current `datasource`. */
   databind() {
     this._databind();
   }
@@ -5750,6 +6139,7 @@ var PacemResizeElement = class PacemResizeElement2 extends PacemEventTarget {
       this._dispatchResize();
     }
   }
+  /** @readonly Gets the last measured size (and position, if `watchPosition` is set) of the observed target. */
   get currentSize() {
     var args = { height: this._previousHeight, width: this._previousWidth };
     if (this.watchPosition) {
@@ -5787,30 +6177,31 @@ var __decorate24 = function(decorators, target, key2, desc) {
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key2, r) : d(target, key2)) || r;
   return c > 3 && r && Object.defineProperty(target, key2, r), r;
 };
-var RouterNavigatingEventName = "navigating";
-var RouterNavigateEventName = "navigate";
-var RouterNavigateEvent = class extends CustomTypedEvent {
-  constructor(path) {
-    super(RouterNavigateEventName, typeof path === "string" ? { path } : path, { cancelable: false, bubbles: false });
-  }
-};
-var RouterNavigatingEvent = class extends CustomTypedEvent {
-  constructor(path) {
-    super(RouterNavigatingEventName, path, { cancelable: true, bubbles: false });
-  }
-};
 var CHECK_PATTERN = /^([\w\.]:)?\/\/[^\/]+/;
 var PacemRouterElement = class PacemRouterElement2 extends PacemEventTarget {
   constructor() {
     super(...arguments);
+    this._onScroll = (e) => {
+      const scrollRestoration = this.scrollRestoration ?? true;
+      if (!scrollRestoration) {
+        return;
+      }
+      const y = Math.floor(Utils.scrollTop);
+      window.history.replaceState(Utils.extend({}, window.history.state, { $scrollY: y }), document.title);
+    };
     this._onPopState = (evt) => {
       if (!Utils.isNull(evt.state) && !this.#cancelingNavigation) {
-        this.path = evt.state.$path;
+        const state = evt.state;
+        this.path = state.$path;
       }
     };
   }
   #cancelingNavigation;
   #template;
+  /**
+   * 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 = {}) {
     const path = this._stringifyMergedState(state);
     const segments = this._segmentateUrl(path);
@@ -5848,12 +6239,13 @@ var PacemRouterElement = class PacemRouterElement2 extends PacemEventTarget {
         this.path = from;
         return;
       }
-      this.state = state;
+      const newState = !poppingState ? Utils.extend({ $scrollY: 0 }, state) : Utils.extend({ $scrollY: 0 }, window.history.state, state);
+      this.state = newState;
+      window.history.scrollRestoration = this.scrollRestoration ?? true ? "manual" : "auto";
       if (poppingState) {
-        window.history.scrollRestoration = "manual";
-        window.history.replaceState(state, title);
+        window.history.replaceState(newState, document.title);
       } else {
-        window.history.pushState(state, title, path);
+        window.history.pushState(newState, title, path);
       }
       if (!Utils.isNullOrEmpty(title)) {
         document.title = title;
@@ -5878,6 +6270,7 @@ var PacemRouterElement = class PacemRouterElement2 extends PacemEventTarget {
   connectedCallback() {
     super.connectedCallback();
     window.addEventListener("popstate", this._onPopState, false);
+    document.addEventListener("scroll", this._onScroll, false);
   }
   viewActivatedCallback() {
     super.viewActivatedCallback();
@@ -5887,6 +6280,7 @@ var PacemRouterElement = class PacemRouterElement2 extends PacemEventTarget {
     }
   }
   disconnectedCallback() {
+    document.removeEventListener("scroll", this._onScroll, false);
     window.removeEventListener("popstate", this._onPopState, false);
     super.disconnectedCallback();
   }
@@ -5940,6 +6334,9 @@ __decorate24([
 __decorate24([
   Watch({ emit: false, converter: PropertyConverters.String })
 ], PacemRouterElement.prototype, "path", void 0);
+__decorate24([
+  Watch({ emit: false, reflectBack: true, converter: PropertyConverters.Boolean })
+], PacemRouterElement.prototype, "scrollRestoration", void 0);
 PacemRouterElement = __decorate24([
   CustomElement({ tagName: P + "-router" })
 ], PacemRouterElement);
@@ -6089,6 +6486,10 @@ var PacemServiceWorkerProxyElement = class PacemServiceWorkerProxyElement2 exten
       }
     });
   }
+  /**
+   * Unsubscribes from push notifications.
+   * @param subscription Subscription to cancel; defaults to the current `pushSubscription`
+   */
   unsubscribe(subscription = this.pushSubscription) {
     return new Promise((resolve, reject) => {
       if (!Utils.isNull(subscription)) {
@@ -6104,6 +6505,10 @@ var PacemServiceWorkerProxyElement = class PacemServiceWorkerProxyElement2 exten
       }
     });
   }
+  /**
+   * Subscribes to push notifications through the registered service worker.
+   * @param publicKey VAPID public key (base64url or raw bytes); defaults to `publicKey`
+   */
   subscribe(publicKey = this.publicKey) {
     return new Promise((resolve, reject) => {
       if (typeof publicKey === "string") {
@@ -6482,6 +6887,7 @@ var PacemTweenElement = class PacemTweenElement2 extends PacemEventTarget {
         this._animate();
     }
   }
+  /** Starts the animation programmatically and returns a promise resolved once it completes. */
   run() {
     return this._animate();
   }
@@ -6658,6 +7064,10 @@ var PacemWebWorkerProxyElement = class PacemWebWorkerProxyElement2 extends Pacem
     this._disposeWorker();
     super.disconnectedCallback();
   }
+  /**
+   * Posts a message to the worker.
+   * @param message Message to send; defaults to the current `message` property
+   */
   send(message = this.message) {
     if (this.disabled) {
       return;
@@ -6707,6 +7117,10 @@ import { Matrix2D } from "@pacem/pacem-foundation";
 // packages/core/dist/esm/components/behavior.js
 var PacemBehavior = class extends PacemEventTarget {
   #items = /* @__PURE__ */ new WeakSet();
+  /**
+   * Registers an element with this behavior, decorating it if it wasn't already registered.
+   * @param element Element to register.
+   */
   register(element) {
     var container = this.#items;
     if (!container.has(element)) {
@@ -6714,6 +7128,10 @@ var PacemBehavior = class extends PacemEventTarget {
       this.decorate(element);
     }
   }
+  /**
+   * Unregisters a previously registered element, undecorating it.
+   * @param element Element to unregister.
+   */
   unregister(element) {
     var container = this.#items;
     if (container.has(element)) {
@@ -6721,6 +7139,7 @@ var PacemBehavior = class extends PacemEventTarget {
       container.delete(element);
     }
   }
+  /** @readonly Determines whether the given element is currently registered with this behavior. */
   has(element) {
     return this.#items.has(element);
   }
@@ -7121,22 +7540,27 @@ var PacemDragDropElement = class PacemDragDropElement2 extends PacemBehavior {
     this.dropTargets = [];
     this.mode = DragDataMode.Self;
   }
+  /** Wires up the `mousedown`/`touchstart` listeners that arm the drag gesture on the given element. */
   decorate(element) {
     const options = { capture: false, passive: false };
     element.addEventListener("mousedown", this._startHandler, false);
     element.addEventListener("touchstart", this._startHandler, options);
   }
+  /** Removes the listeners set up by {@link decorate}. */
   undecorate(element) {
     const options = { capture: false, passive: false };
     element.removeEventListener("mousedown", this._startHandler, false);
     element.removeEventListener("touchstart", this._startHandler, options);
   }
+  /** Registers a listener for a {@link DragDropEventType} lifecycle event. */
   addEventListener(type, listener, useCapture) {
     super.addEventListener(type, listener, useCapture);
   }
+  /** Unregisters a listener previously added for a {@link DragDropEventType} lifecycle event. */
   removeEventListener(type, listener, useCapture) {
     super.removeEventListener(type, listener, useCapture);
   }
+  /** Dispatches a {@link DragDropEvent}, clearing internal per-element bookkeeping once the drag ends. */
   dispatchEvent(evt) {
     if (evt.type === DragDropEventType.End) {
       DEL_VAL2(evt.detail.element, MOUSE_DOWN);
@@ -7343,11 +7767,13 @@ var PacemRescaleElement = class PacemRescaleElement2 extends PacemBehavior {
       ));
     };
   }
+  /** Adds the resize-handle frame (see {@link RescaleHandle}) around the given element. */
   decorate(element) {
     const el = element, css = getComputedStyle(el);
     Utils.addClass(el, PCSS + "-rescalable");
     this._setFrame(el);
   }
+  /** Removes the resize-handle frame set up by {@link decorate}. */
   undecorate(element) {
     const el = element;
     Utils.removeClass(el, PCSS + "-rescalable");
@@ -7576,6 +8002,7 @@ var PacemRotateElement = class PacemRotateElement2 extends PacemBehavior {
       ));
     };
   }
+  /** Wires up the `mousedown`/`touchstart` listeners that arm the rotate gesture on the given element. */
   decorate(element) {
     const el = element;
     Utils.addClass(el, PCSS + "-rotatable");
@@ -7583,6 +8010,7 @@ var PacemRotateElement = class PacemRotateElement2 extends PacemBehavior {
     element.addEventListener("mousedown", this._startHandler, false);
     element.addEventListener("touchstart", this._startHandler, options);
   }
+  /** Removes the listeners set up by {@link decorate}. */
   undecorate(element) {
     const el = element;
     Utils.removeClass(el, PCSS + "-rotatable");
@@ -7843,12 +8271,14 @@ var PacemSwipeElement = class PacemSwipeElement2 extends PacemBehavior {
       this._undo(el);
     };
   }
+  /** Wires up the `pointerdown` listener that arms the swipe gesture on the given element. */
   decorate(element) {
     if (element instanceof HTMLElement || element instanceof SVGElement) {
       Utils.addClass(element, PCSS + "-swipe");
     }
     element.addEventListener("pointerdown", this._prepareHandler, false);
   }
+  /** Removes the listener set up by {@link decorate}. */
   undecorate(element) {
     if (element instanceof HTMLElement || element instanceof SVGElement) {
       Utils.removeClass(element, PCSS + "-swipe");
@@ -7942,10 +8372,12 @@ var TweenAnimationElement = class extends AnimationElement {
     super();
     this._tweener = _tweener;
   }
+  /** @readonly Gets the {@link TweenService} instance driving this animation. */
   get tweener() {
     return this._tweener;
   }
   #cancelToken = false;
+  /** Starts (or restarts) the tween and returns a promise resolved once it completes. */
   startAnimation() {
     this.#cancelToken = false;
     return new Promise((resolve, _) => {
@@ -7956,6 +8388,7 @@ var TweenAnimationElement = class extends AnimationElement {
       }).then(resolve);
     });
   }
+  /** Cancels the running tween. */
   cancelAnimation() {
     this.#cancelToken = true;
   }
@@ -8013,6 +8446,7 @@ var PacemColorAnimationElement = class PacemColorAnimationElement2 extends Tween
   _parseColor(clr) {
     return Colors2.hsl(Colors2.parse(clr));
   }
+  /** @inheritdoc */
   tweenInterpolationCallback(time, progress) {
     const from = this.#from, to = this.#to;
     const hsla = {
@@ -8044,6 +8478,7 @@ var __decorate42 = function(decorators, target, key2, desc) {
 var DEFAULT_FROM2 = 0;
 var DEFAULT_TO2 = 1;
 var PacemNumberAnimationElement = class PacemNumberAnimationElement2 extends TweenAnimationElement {
+  /** @inheritdoc */
   tweenInterpolationCallback(time, progress) {
     const to = this.to ?? DEFAULT_TO2, from = this.from ?? DEFAULT_FROM2;
     return (to - from) * progress + from;
@@ -8069,6 +8504,7 @@ var __decorate43 = function(decorators, target, key2, desc) {
 var DEFAULT_FROM3 = { x: 0, y: 0 };
 var DEFAULT_TO3 = { x: 1, y: 1 };
 var PacemPointAnimationElement = class PacemPointAnimationElement2 extends TweenAnimationElement {
+  /** @inheritdoc */
   tweenInterpolationCallback(time, progress) {
     const to = this.to ?? DEFAULT_TO3, from = this.from ?? DEFAULT_FROM3;
     return {
@@ -8095,6 +8531,7 @@ var __decorate44 = function(decorators, target, key2, desc) {
   return c > 3 && r && Object.defineProperty(target, key2, r), r;
 };
 var PacemStoryboardElement = class PacemStoryboardElement2 extends PacemItemsContainerElement {
+  /** @inheritdoc */
   validate(item) {
     return item instanceof AnimationElement;
   }
@@ -8135,12 +8572,14 @@ var PacemStoryboardElement = class PacemStoryboardElement2 extends PacemItemsCon
     }
     return Promise.all(promises);
   }
+  /** Cancels every running {@link Timeline} in this storyboard. */
   cancelAnimation() {
     const ds = this._adaptedDatasource || [];
     for (let timeline of ds) {
       timeline.cancelAnimation();
     }
   }
+  /** Starts (or restarts) every {@link Timeline} in this storyboard. */
   startAnimation() {
     return this._animate(true);
   }
@@ -8237,6 +8676,13 @@ function buildDiffOptions(modeOrOutput, outputOrCssAdd, cssAddOrRemove, cssRemov
   };
 }
 var Transforms2 = class {
+  /**
+   * Wraps every case-insensitive occurrence of each whitespace-separated token of `query` found in `src`
+   * (skipping matches inside HTML tags) with a `<span class="{css}">` highlight wrapper.
+   * @param src Source HTML/text to search within.
+   * @param query Whitespace-separated search terms.
+   * @param css CSS class applied to the highlight `<span>`. Defaults to `{PCSS}-highlight`.
+   */
   static highlight(src, query, css = PCSS + "-highlight") {
     if (!query || !src)
       return src;
@@ -8278,9 +8724,11 @@ var Transforms2 = class {
       return acc;
     }, "");
   }
+  /** Left-pads `src` (stringified) to `length` characters using `pad`; see {@link Utils.leftPad}. */
   static padleft(src, length, pad) {
     return Utils.leftPad("" + src, length, pad);
   }
+  /** Formats a byte count `src` as a human-readable size string (`B`/`kB`/`MB`/`GB`), or `'-'` if not a positive number. */
   static size(src) {
     if (!(src > 0))
       return "-";
@@ -8292,12 +8740,25 @@ var Transforms2 = class {
       return (src / 1048576).toFixed(2) + " MB";
     return (src / 1073741824).toFixed(2) + " GB";
   }
+  /**
+   * Formats a decimal-degrees number `src` as degrees/minutes/seconds (e.g. `41° 53' 24"`).
+   * @param src Decimal degrees value (sign indicates direction).
+   * @param degSeparator Text following the degrees component.
+   * @param minSeparator Text following the minutes component.
+   * @param secSeparator Text following the seconds component.
+   */
   static decToDeg(src, degSeparator = "\xB0 ", minSeparator = "' ", secSeparator = '"') {
     const sign = Math.sign(src);
     src = Math.abs(src);
     const deg = Math.floor(src), min0 = (src - deg) * 60, min = Math.floor(min0), sec0 = (min0 - min) * 60, sec = Math.floor(sec0);
     return (sign < 0 ? "-" : "") + deg + degSeparator + min + minSeparator + sec + secSeparator;
   }
+  /**
+   * Formats a date-like value `src` (parsed via {@link Utils.parseDate}) as text.
+   * @param src Date, timestamp, or parseable date string.
+   * @param format Either a named shorthand (`'iso'`, `'isodate'`, `'localdate'`, `'time'`/`'localtime'`, `'full'`, or the default locale date format) or an `Intl.DateTimeFormatOptions` object.
+   * @param culture BCP 47 locale to format with. Defaults to the browser's language.
+   */
   static date(src, format, culture) {
     var date = Utils.parseDate(src), lang = culture || navigator.language;
     if (Utils.isNull(format) || typeof format === "string") {
@@ -8324,6 +8785,13 @@ var Transforms2 = class {
       return date.toLocaleString(culture, format);
     }
   }
+  /**
+   * Formats the elapsed time between `start` and `end`.
+   * @param start Start date-like value.
+   * @param end End date-like value.
+   * @param format Either an `Intl.DateTimeFormatOptions` (formatted as a UTC duration, optionally sign-prefixed via `sign: true`), or omitted for the legacy `"{d}d {h}h {m}m {s}s {ms}ms"` textual format.
+   * @param culture BCP 47 locale to format with (only used with `Intl.DateTimeFormatOptions`). Defaults to the browser's language.
+   */
   static timespan(start, end, format, culture) {
     const startDate = Utils.parseDate(start), endDate = Utils.parseDate(end), span = endDate.valueOf() - startDate.valueOf(), sign = span < 0 ? "-" : "", elapsed = Math.abs(span);
     if (typeof format === "object") {
@@ -8333,18 +8801,26 @@ var Transforms2 = class {
     const msecsPerDay = 864e5, msecsPerHr = 36e5, msecsPerMin = 6e4, days = Math.floor(elapsed / msecsPerDay), hrs = Math.floor(elapsed % msecsPerDay / msecsPerHr), mins = Math.floor(elapsed % msecsPerHr / msecsPerMin), secs = Math.floor(elapsed % msecsPerMin / 1e3), msecs = Math.floor(elapsed % 1e3);
     return `${sign}${days}d ${hrs}h ${mins}m ${secs}s ${msecs}ms`;
   }
+  /** Formats `src` as a currency amount using `Intl.NumberFormat`. @param currency ISO 4217 currency code. @param culture BCP 47 locale. Defaults to the browser's language. */
   static currency(src, currency, culture) {
     return new Intl.NumberFormat(culture ?? navigator.language, { style: "currency", currency }).format(src);
   }
+  /**
+   * Formats `src` as a number using `Intl.NumberFormat`.
+   * @param formatOrCulture Either a BCP 47 locale string, or `Intl.NumberFormatOptions` (in which case `culture` supplies the locale).
+   * @param culture BCP 47 locale, used only when `formatOrCulture` is a format-options object. Defaults to the browser's language.
+   */
   static number(src, formatOrCulture, culture) {
     if (typeof formatOrCulture === "string") {
       return new Intl.NumberFormat(formatOrCulture || navigator.language).format(src);
     }
     return new Intl.NumberFormat(culture ?? navigator.language, formatOrCulture).format(src);
   }
+  /** Filters `src` with `filter`; a thin wrapper over `Array.prototype.filter` usable from template expressions. */
   static filter(src, filter) {
     return src.filter(filter);
   }
+  /** Sorts `src` in place (ascending, via `>`/`<` comparison), optionally by a property path when items are objects. @param prop Property name to sort by; omit to compare items directly. */
   static orderby(src, prop) {
     return src.sort((a, b) => {
       if (!Utils.isNullOrEmpty(prop)) {
@@ -8355,31 +8831,39 @@ var Transforms2 = class {
     });
   }
   // #region RegExp
+  /** Tests `input` against a `RegExp` built from `pattern`/`flags`. Registered as `regex.isMatch`. */
   static isMatch(input, pattern, flags) {
     return new RegExp(pattern, flags).test(input);
   }
   // #endregion
   // #region shortcuts from 'Utils'
+  /** Template-expression shortcut for {@link Utils.isEmpty}. */
   static isEmpty(obj2) {
     return Utils.isEmpty(obj2);
   }
+  /** Template-expression shortcut for {@link Utils.isNull}. */
   static isNull(obj2) {
     return Utils.isNull(obj2);
   }
+  /** Template-expression shortcut for {@link Utils.isNullOrEmpty}. */
   static isNullOrEmpty(obj2) {
     return Utils.isNullOrEmpty(obj2);
   }
+  /** Reads a CSS custom property's value off the document; see {@link Utils.Css.getVariableValue}. Registered as `cssvar`. */
   static getCssVariable(name) {
     return Utils.Css.getVariableValue(name);
   }
+  /** Reads a query-string parameter's value off the current URL; see {@link Utils.URIs.parseQuery}. Registered as `querystring`. */
   static getQuerystring(name) {
     return Utils.URIs.parseQuery()[name];
   }
   // #endregion
   // #region shortcuts from 'CustomElementUtils'
+  /** Template-expression shortcut for {@link CustomElementUtils.Theme}'s `importWebFonts`. */
   static importThemeWebFonts() {
     return CustomElementUtils.Theme.importWebFonts();
   }
+  /** Template-expression shortcut for {@link CustomElementUtils.findHostContext}. Registered as `host`. */
   static findHostContext(element) {
     return CustomElementUtils.findHostContext(element);
   }
@@ -8480,6 +8964,10 @@ export {
   Regex,
   Repeater,
   RepeaterItem,
+  RouterNavigateEvent,
+  RouterNavigateEventName,
+  RouterNavigatingEvent,
+  RouterNavigatingEventName,
   Storage,
   TemplateElement,
   Throttle,