@pacem/pacem 1.0.0-bessel → 1.0.0-dirac

package/dist/browser/pacem-core.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem v1.0.0-dirac (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -24,22 +24,39 @@
         output['css'] = css;
         return output;
     }
+    /**
+    * Collection of ready-made {@link Easing} functions, each paired with its CSS timing-function equivalent.
+    */
     const 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)'),
     };
     //}
 
     // namespace Pacem {
+    /**
+     * 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.
+     */
     class DeepCloner {
         constructor() {
         }
+        /** Deep-clones `obj`; see {@link DeepCloner} for what gets cloned vs. passed through by reference. */
         static clone(obj) {
             return new DeepCloner()._clone(obj);
         }
@@ -110,13 +127,27 @@
             this._jsonFnWeakMap.delete(fn);
         }
     }
+    /**
+     * 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.
+     */
     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(obj, options) {
             return new Json(options)._serialize(obj);
         }
+        /** Deserializes a string produced by {@link serialize}, restoring references, `RegExp`s, `Element`s and functions. */
         static deserialize(json) {
             return new Json()._deserialize(json);
         }
@@ -240,6 +271,12 @@
     //}
 
     //namespace Pacem {
+    /**
+     * 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).
+     */
     class DeferPromise {
         constructor() {
             this.deferred = null;
@@ -248,6 +285,7 @@
                 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);
         }
@@ -259,14 +297,17 @@
             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;
@@ -277,40 +318,56 @@
     // namespace Pacem {
     const PACEM_CORE_DEFAULT = 'pacem';
     const DEFAULT_DOWNLOAD_FILENAME = 'download';
+    /** Ready-to-use event listener that only calls `evt.stopPropagation()`; handy as an `addEventListener` callback without allocating a closure. */
     const stopPropagationHandler = (evt) => {
         evt.stopPropagation();
     };
+    /** Ready-to-use event listener that only calls `evt.preventDefault()`; handy as an `addEventListener` callback without allocating a closure. */
     const preventDefaultHandler = (evt) => {
         evt.preventDefault();
     };
+    /** Ready-to-use event listener that calls both `evt.preventDefault()` and `evt.stopPropagation()`. */
     const avoidHandler = (evt) => {
         evt.preventDefault();
         evt.stopPropagation();
     };
     const SEGMENT_PATTERN = /^\/[^\/]+/;
     const ROUTE_SEGMENT_PATTERN = /\/\{([a-z\$_][\w]*)\??\}/;
+    /**
+     * 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).
+     */
     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 root = window['Pacem'];
             var id = (root && root.Configuration && root.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 pacemFoundation.Keys.uniqueId();
         }
+        /** Generates a unique short code string. */
         static uniqueCode() {
             return pacemFoundation.Keys.uniqueCode();
         }
+        /** Generates a random string of the given `length`. */
         static randomString(length) {
             return pacemFoundation.Keys.randomString(length);
         }
+        /** Parses a date-like value (ISO string, `Date`, or timestamp) into a `Date`. */
         static parseDate(input) {
             return pacemFoundation.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);
@@ -378,6 +435,7 @@
                 return filter;
             }
         }
+        /** Escapes `input` for safe use as a CSS identifier/selector fragment. */
         static cssEscape(input) {
             return escape(input).replace('%', '\\');
         }
@@ -385,9 +443,11 @@
         static { 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, value) {
                 getComputedStyle(document.documentElement).setProperty(name, value);
             },
@@ -417,6 +477,7 @@
                 }
                 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;
@@ -443,6 +504,7 @@
             leftPad: pacemFoundation.Strings.leftPad,
             format: pacemFoundation.Strings.format,
             diff: pacemFoundation.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 || '';
@@ -461,6 +523,7 @@
             load: pacemFoundation.Imaging.loadImage,
             resize: pacemFoundation.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();
@@ -478,15 +541,19 @@
                 }
             });
         }
+        /** 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);
         }
@@ -572,6 +639,7 @@
             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']];
@@ -818,10 +886,12 @@
         }
         // #endregion
         // #region DOM
+        /** Whether the document (including module scripts) has fully finished loading (`document.readyState === 'complete'`). */
         static isDOMReady() {
             // Must exclude 'interactive' state since module script haven't been processed yet.
             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('DOMContentLoaded', listener, false);
             // window 'load' event fires after 'DOMCOntentLoaded' since includes images load.
@@ -850,13 +920,16 @@
             }
             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(obj) {
             if (Utils.isNull(obj)) {
                 return obj;
@@ -866,6 +939,7 @@
         static { this.Browsers = {
             detect: pacemFoundation.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) {
@@ -881,7 +955,9 @@
             }
             return retval;
         }
+        /** Cookie helpers, preferring the native `cookieStore` API when available and falling back to `document.cookie` parsing otherwise. */
         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 = [];
@@ -899,6 +975,7 @@
                     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)) {
@@ -925,6 +1002,7 @@
                 return retval;
             }
         }; }
+        /** 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 });
@@ -932,6 +1010,7 @@
             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);
@@ -940,6 +1019,7 @@
                 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) {
@@ -949,6 +1029,7 @@
                 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) {
@@ -958,6 +1039,7 @@
                 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);
@@ -968,15 +1050,19 @@
         }
         //#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);
@@ -1012,9 +1098,11 @@
                 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);
         }
@@ -1042,9 +1130,11 @@
         static deserializeTransform(obj) {
             return Utils.Css.deserializeTransform(obj);
         }
+        /** 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);
         }
@@ -1055,12 +1145,15 @@
             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 /*window.pageYOffset*/ || 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 /*window.pageXOffset*/ || 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 {
@@ -1136,16 +1229,20 @@
         }
         // #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(obj) {
             return pacemFoundation.NullChecker.isEmpty(obj) && !(obj instanceof Node);
         }
+        /** Type-guarding test for `obj` being `null` or `undefined`. */
         static isNull(obj) {
             return pacemFoundation.NullChecker.isNull(obj);
         }
         // 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);
         }
@@ -1164,6 +1261,7 @@
         }
         /** Legacy alias for Object.assign(). */
         static { this.extend = Object.assign; }
+        /** Deep-clones `obj`; see {@link DeepCloner}. */
         static clone(obj) {
             if (obj === undefined)
                 return undefined;
@@ -1173,6 +1271,7 @@
         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())));
         }
@@ -1196,7 +1295,15 @@
         }
         //#endregion
         //#region Net
+        /** URL/route parsing and formatting helpers, chiefly backing the router (`{segment}`/`{segment?}` template resolution, query-string parsing, route metadata). */
         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) {
                 // replace segments
                 for (let name in parameters || {}) {
@@ -1219,6 +1326,14 @@
                 }
                 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) +
@@ -1227,6 +1342,7 @@
                         .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;
@@ -1237,9 +1353,11 @@
                 });
                 return obj;
             },
+            /** 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 = [];
@@ -1259,6 +1377,7 @@
                 }
                 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);
@@ -1267,6 +1386,16 @@
                 }
                 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)) {
@@ -1351,6 +1480,7 @@
     }
     // }
 
+    /** String tokens accepted by {@link CustomEventUtils.matchModifiers} to describe a keyboard/mouse modifier. */
     var EventKeyModifier;
     (function (EventKeyModifier) {
         EventKeyModifier["AltKey"] = "Alt";
@@ -1358,11 +1488,24 @@
         EventKeyModifier["ShiftKey"] = "Shift";
         EventKeyModifier["MetaKey"] = "Cmd";
     })(EventKeyModifier || (EventKeyModifier = {}));
+    /** Static helpers for inspecting and normalizing native/custom events (coordinates, keyboard modifiers, type checks). */
     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(evt, type) {
             return evt instanceof type;
             // || CustomElementUtils.getAttachedPropertyValue(evt, 'pacem:custom-event') === evt.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) {
@@ -1382,6 +1525,11 @@
                 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) {
@@ -1402,6 +1550,13 @@
             }
             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) {
             // this an optimistic BUGGED workaround due to a damn' Edge bug: https://github.com/Microsoft/ChakraCore/issues/3952
             if (!(evt instanceof type)) {
@@ -1413,7 +1568,17 @@
 
     /// <reference path="utils-customevent.ts" />
     // namespace Pacem {
+    /**
+     * 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.
+     */
     class CustomTypedEvent extends CustomEvent /* new in TypeScript v2.7.1 -> */ {
+        /**
+         * @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: detail }, eventInit || {}));
             CustomEventUtils.fixEdgeCustomEventSubClassInstance(this, this.constructor);
@@ -1432,7 +1597,20 @@
         return false;
     }
     // TODO: make inherit from CustomTypedEvent
+    /**
+     * 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.
+     */
     class CustomUIEvent 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: detail }), (!(eventInit instanceof Event) && eventInit) || {}));
             const originalEvent = orig || eventInit;
@@ -1485,27 +1663,44 @@
             return this.#coords?.screen.y;
         }
     }
+    /** Event name dispatched whenever an observed attribute changes; see {@link AttributeChangeEvent}. */
     const AttributeChangeEventName = 'attributechange';
+    /**
+     * Dispatched by elements registered with the {@link CustomElement} decorator whenever one of their
+     * observed attributes changes, mirroring the native `attributeChangedCallback` as a DOM event.
+     */
     class AttributeChangeEvent extends CustomTypedEvent {
         constructor(args) {
             super(AttributeChangeEventName, args);
         }
     }
+    /** Event name dispatched whenever a `@Watch`-decorated property changes value; see {@link PropertyChangeEvent}. */
     const PropertyChangeEventName = 'propertychange';
+    /**
+     * 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.
+     */
     class PropertyChangeEvent extends CustomTypedEvent {
         constructor(args) {
             super(PropertyChangeEventName, args);
         }
     }
     // #region NAVIGATING
+    /** Event name dispatched by a router *before* a navigation is committed; see {@link RouterNavigatingEvent}. Cancelable: calling `preventDefault()` aborts the navigation. */
     const RouterNavigatingEventName = 'navigating';
+    /** Event name dispatched by a router *after* a navigation has been committed; see {@link RouterNavigateEvent}. */
     const RouterNavigateEventName = 'navigate';
+    /** Dispatched by a router once it has navigated to a new `path` (not cancelable — the navigation already happened). */
     class RouterNavigateEvent 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 });
         }
     }
+    /** Dispatched by a router right before navigating to `path`; cancelable, so a listener can call `preventDefault()` to abort the navigation. */
     class RouterNavigatingEvent extends CustomTypedEvent {
+        /** @param path Destination path about to be navigated to. */
         constructor(path) {
             super(RouterNavigatingEventName, path, { cancelable: true, bubbles: false });
         }
@@ -1513,16 +1708,25 @@
     // #endregion
     //}
 
+    /**
+    * `step` event dispatched on every animation frame of a running tween, carrying the current progress and value.
+    */
     class AnimationEvent extends CustomTypedEvent {
         constructor(args) {
             super("step", args);
         }
     }
+    /**
+    * `end` event dispatched once a tween/animation completes.
+    */
     class AnimationEndEvent extends CustomEvent {
         constructor() {
             super('end');
         }
     }
+    /**
+    * `start` event dispatched when a tween/animation begins.
+    */
     class AnimationStartEvent extends CustomEvent {
         constructor() {
             super('start');
@@ -1531,7 +1735,20 @@
     //}
 
     //namespace Pacem.Animations {
+    /**
+    * Runs `requestAnimationFrame`-driven numeric tweens between two values, invoking a callback on each frame.
+    */
     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, to, duration, delay = 0, easing = Easings.linear, callback = null) {
             return new Promise((resolve, _) => {
                 const now = (performance && performance.now()) || Date.now();
@@ -1564,6 +1781,10 @@
     //}
 
     // namespace Pacem.Animations {
+    /**
+    * `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`.
+    */
     class Timer {
         #fps;
         #callback;
@@ -1584,9 +1805,15 @@
             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);
         }
@@ -1604,6 +1831,7 @@
     });
 
     //namespace Pacem.Net {
+    /** HTTP verbs accepted by {@link Fetcher.method} / {@link Http}. */
     var HttpMethod;
     (function (HttpMethod) {
         HttpMethod["Get"] = "GET";
@@ -1616,10 +1844,15 @@
         HttpMethod["Connect"] = "CONNECT";
         HttpMethod["Trace"] = "TRACE";
     })(HttpMethod || (HttpMethod = {}));
+    /** Event name dispatched with the raw fetch result payload; see {@link Fetcher.result}. */
     const FetchResultEventName = 'fetchresult';
+    /** Event name dispatched when a {@link Fetcher}'s request fails. */
     const FetchErrorEventName = 'error';
+    /** Event name dispatched when a {@link Fetcher}'s request completes successfully. */
     const FetchSuccessEventName = 'success';
+    /** Static helpers for working with fetch `Response`s. */
     class Fetcher {
+        /** 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";
         }
@@ -1629,17 +1862,22 @@
     /// <reference path="../promise.ts" />
     // namespace Pacem.Net {
     const noop = () => { };
+    /** Error thrown by {@link Http.request} when a request fails outright or completes with a non-2xx status. */
     class StatusCodeError 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;
         }
     }
-    /** @deprecated */
+    /** Wraps a completed `XMLHttpRequest` produced by {@link Http.request}, exposing its status, headers and body in convenient forms.
+     * @deprecated */
     class Response {
+        /** @param req The completed `XMLHttpRequest`. @param processTime Elapsed request time, in milliseconds. */
         constructor(req, processTime) {
             if (!req)
                 return;
@@ -1650,20 +1888,25 @@
             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 === undefined && 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']));
         }
@@ -1679,9 +1922,13 @@
             });
             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; }
         /**
          * Short-hand utility for getting or parsing json content (if any).
@@ -1698,7 +1945,11 @@
                 }
         }
     }
-    /** @deprecated */
+    /**
+     * Legacy `XMLHttpRequest`-based HTTP client, superseded by the standard `fetch` API and {@link Fetcher}.
+     * Kept for backward compatibility.
+     * @deprecated
+     */
     class Http {
         constructor() { }
         /**
@@ -1844,6 +2095,9 @@
         /** Terminating the drag-drop activities. */
         DragDropEventType["End"] = "dragend";
     })(DragDropEventType || (DragDropEventType = {}));
+    /**
+    * Base class shared by the drag & drop event-args classes; wraps a {@link DragDropEventArgs} builder and exposes its common, read-only facets.
+    */
     class DragDropEventArgsBaseClass {
         constructor(_builder) {
             this._builder = _builder;
@@ -1870,32 +2124,46 @@
             return pacemFoundation.Point.add(args.initialDelta, /* included in `initialDelta` for perf sake => { x: this._builder.scroll.left, y: this._builder.scroll.top },*/ pacemFoundation.Point.subtract(args.origin, args.currentPosition));
         }
     }
+    /**
+    * Event args dispatched with the {@link DragDropEventType.Init} event, mutable so listeners can override
+    * the `placeholder` and `data` before the drag actually starts.
+    */
     class DragDropInitEventArgsClass extends DragDropEventArgsBaseClass {
         constructor(_builder) {
             super(_builder);
             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));
         }
     }
+    /**
+    * Read-only event args dispatched with the drag/drop lifecycle events other than `draginit` (start, drag, drop, over, out, end).
+    */
     class DragDropEventArgsClass extends DragDropEventArgsBaseClass {
         constructor(_builder, _placeholder = _builder.placeholder, _data = _builder.data) {
             super(_builder);
             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));
         }
     }
+    /**
+    * Custom UI event dispatched throughout the drag & drop lifecycle (see {@link DragDropEventType}).
+    */
     class DragDropEvent extends CustomUIEvent {
         constructor(type, args, eventInit, evt) {
             super(type, args, eventInit, evt);
@@ -1904,40 +2172,65 @@
     //}
 
     //namespace Pacem.UI {
+    /**
+    * Enumerates the resize handles a {@link Rescaler} can expose around a rescalable element.
+    */
     var RescaleHandle;
     (function (RescaleHandle) {
+        /** All four sides/corners are enabled. */
         RescaleHandle["All"] = "all";
+        /** The top edge (and its corners) is enabled. */
         RescaleHandle["Top"] = "top";
+        /** The left edge (and its corners) is enabled. */
         RescaleHandle["Left"] = "left";
+        /** The right edge (and its corners) is enabled. */
         RescaleHandle["Right"] = "right";
+        /** The bottom edge (and its corners) is enabled. */
         RescaleHandle["Bottom"] = "bottom";
     })(RescaleHandle || (RescaleHandle = {}));
+    /**
+    * Enumerates the events dispatched throughout the rescale gesture lifecycle.
+    */
     var RescaleEventType;
     (function (RescaleEventType) {
+        /** First rescaling act. */
         RescaleEventType["Start"] = "rescalestart";
+        /** Any rescaling act. */
         RescaleEventType["Rescale"] = "rescale";
+        /** Terminating the rescaling activities. */
         RescaleEventType["End"] = "rescaleend";
     })(RescaleEventType || (RescaleEventType = {}));
+    /**
+    * Read-only event args dispatched with the rescale gesture lifecycle events.
+    */
     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));
         }
     }
+    /**
+    * Custom UI event dispatched throughout the rescale gesture lifecycle (see {@link RescaleEventType}).
+    */
     class RescaleEvent extends CustomUIEvent {
         constructor(type, args, eventInit, evt) {
             super(type, args, eventInit, evt);
@@ -1945,32 +2238,49 @@
     }
     //}
 
+    /**
+    * Enumerates the events dispatched throughout the rotate gesture lifecycle.
+    */
     var RotateEventType;
     (function (RotateEventType) {
+        /** First rotating act. */
         RotateEventType["Start"] = "rotatestart";
+        /** Any rotating act. */
         RotateEventType["Rotate"] = "rotate";
+        /** Terminating the rotating activities. */
         RotateEventType["End"] = "rotateend";
     })(RotateEventType || (RotateEventType = {}));
+    /**
+    * Read-only event args dispatched with the rotate gesture lifecycle events.
+    */
     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));
         }
     }
+    /**
+    * Custom UI event dispatched throughout the rotate gesture lifecycle (see {@link RotateEventType}).
+    */
     class RotateEvent extends CustomUIEvent {
         constructor(type, args, eventInit, evt) {
             super(type, args, eventInit, evt);
@@ -1978,21 +2288,38 @@
     }
     //}
 
+    /**
+    * Enumerates the events dispatched throughout the swipe gesture lifecycle.
+    */
     var SwipeEventType;
     (function (SwipeEventType) {
+        /** Dispatched when the swipe gesture ends (release). */
         SwipeEventType["Swipe"] = "swipe";
+        /** Dispatched while the pointer is dragging the element around. */
         SwipeEventType["Pan"] = "pan";
+        /** Dispatched when the swipe ends and its resolved direction is leftward. */
         SwipeEventType["SwipeLeft"] = "swipeleft";
+        /** Dispatched when the swipe ends and its resolved direction is rightward. */
         SwipeEventType["SwipeRight"] = "swiperight";
+        /** Dispatched when the swipe ends and its resolved direction is upward. */
         SwipeEventType["SwipeUp"] = "swipeup";
+        /** Dispatched when the swipe ends and its resolved direction is downward. */
         SwipeEventType["SwipeDown"] = "swipedown";
         // end of swipe animation
+        /** Dispatched when the snap/bounce-back animation following a swipe completes. */
         SwipeEventType["SwipeAnimationEnd"] = "swipeanimationend";
+        /** Dispatched when the snap/bounce-back animation following a leftward swipe completes. */
         SwipeEventType["SwipeLeftAnimationEnd"] = "swipeleftanimationend";
+        /** Dispatched when the snap/bounce-back animation following a rightward swipe completes. */
         SwipeEventType["SwipeRightAnimationEnd"] = "swiperightanimationend";
+        /** Dispatched when the snap/bounce-back animation following an upward swipe completes. */
         SwipeEventType["SwipeUpAnimationEnd"] = "swipeupanimationend";
+        /** Dispatched when the snap/bounce-back animation following a downward swipe completes. */
         SwipeEventType["SwipeDownAnimationEnd"] = "swipedownanimationend";
     })(SwipeEventType || (SwipeEventType = {}));
+    /**
+    * Read-only event args dispatched with the swipe gesture lifecycle events.
+    */
     class SwipeEventArgsClass {
         constructor(_builder) {
             this._builder = _builder;
@@ -2002,6 +2329,7 @@
             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')
@@ -2033,13 +2361,18 @@
             const inertia = this._builder.inertia ?? 8;
             return -Math.log(.01 /* 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));
         }
     }
+    /**
+    * Custom typed event dispatched throughout the swipe gesture lifecycle (see {@link SwipeEventType}).
+    */
     class SwipeEvent extends CustomTypedEvent {
         constructor(type, args, eventInit) {
             super(type, args, eventInit);
@@ -2068,6 +2401,7 @@
         get SwipeEventType () { return SwipeEventType; }
     });
 
+    /** Dispatched by an {@link Iterative} container whenever its `index` changes. */
     class CurrentIndexChangeEvent extends CustomTypedEvent {
         constructor(args) {
             super('currentindexchange', args);
@@ -2076,11 +2410,16 @@
     //}
 
     /// <reference path="events.ts" />
+    /** 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. */
     const Type = Function;
     // #region CONSTS
+    /** Key used to attach, on an element's constructor, the list of its `@Watch`-decorated (watched) property descriptors. */
     const WATCH_PROPS_VAR = 'pacem:properties';
+    /** Key used to attach, on an element instance, the list of attribute names currently holding a pending (not-yet-evaluable) binding expression. */
     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. */
     const INSTANCE_HOST_VAR = 'pacem:custom-element:host';
+    /** Key used to attach, on an element instance, its binding-expression evaluation scope object. */
     const INSTANCE_SCOPE_VAR = 'pacem:custom-element:scope';
     // #endregion
     //}
@@ -2089,37 +2428,66 @@
     var root;
     /** the overall customelement prefix */
     const P = (root = window['Pacem'])?.Configuration?.prefix ?? 'pacem';
+    /** 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}. */
     const PCSS = root?.Configuration?.css ?? P;
     //}
 
     //namespace Pacem {
+    /** 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`. */
     class TemplateElement extends HTMLElement {
     }
     //}
 
-    /// <reference path="expression.ts" />
-    /// <reference path="promise.ts" />
-    /// <reference path="prefix.ts" />
-    /// <reference path="trees/json.ts" />
-    /// <reference path="utils.ts" />
     // namespace Pacem {
     const PACEM_BAG = '__pacem__';
     // {{ binding.expression }}
     const bindingPattern = /^\{\{(.|\n)+\}\}$/;
     // TODO: CSP-proof binding (no unsafe-eval)
     // binding syntax example: `{ binding: { source: ^item.property.path, binder: $pacem.func, parameters: [ ^index, 'foo', : host._baz], mode: 'twoway' } }`
+    /**
+     * 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.
+     */
     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.isConnected && !(element instanceof PacemEventTarget)){
+                //     reject('Invalid element.');
+                // }
+                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;
@@ -2130,9 +2498,16 @@
             } 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))
@@ -2141,6 +2516,12 @@
                 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))
@@ -2149,6 +2530,15 @@
                 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(key, tagName, attrs, appendTo = document.body) {
             const _p = Utils.core;
             var _imports = _p['imports'] = _p['imports'] || {};
@@ -2178,7 +2568,9 @@
                 }
             });
         }
+        /** Theming-related helpers. */
         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) {
                     // check if the string is wrapped around quotes to escape ';' chars
@@ -2216,6 +2608,14 @@
                 return Promise.all(promises);
             }
         }; }
+        /**
+         * 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, value) {
             /*(target[PACEM_BAG] = target[PACEM_BAG] || {})[name] = value;*/
             if (Utils.isNull(target))
@@ -2230,9 +2630,16 @@
             else
                 bag[name] = value;
         }
+        /** Removes a value previously stored via {@link setAttachedPropertyValue}. */
         static deleteAttachedPropertyValue(target, name) {
             CustomElementUtils.setAttachedPropertyValue(target, name, undefined);
         }
+        /**
+         * 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)) {
@@ -2278,6 +2685,17 @@
             }
             return { target: { value: ref, name: name }, parent: { value: parent || scope, path: path.substring(0, ndx) }, root: { value: root, 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, value) {
             var obj = CustomElementUtils.resolvePath(path, element);
             var current = obj.target.value;
@@ -2308,6 +2726,7 @@
                 }
             }
         }
+        /** Reads the value at the given dotted `path`, rooted at `element`; see {@link resolvePath}. */
         static get(element, path) {
             var obj = CustomElementUtils.resolvePath(path, element);
             return obj && obj.target && obj.target.value;
@@ -2328,12 +2747,27 @@
             //    logFn(`Element "${element.constructor.name}" isn't attached to any context yet.`);
             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;
@@ -2347,12 +2781,20 @@
             }
             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 = [];
@@ -2367,10 +2809,16 @@
             }
             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, arr) => {
@@ -2432,6 +2880,14 @@
             } 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) {
             // navigate through the DOM hierarchy
             const walker = document.createTreeWalker(template.content, NodeFilter.SHOW_ELEMENT + /* traverse templates' content */ NodeFilter.SHOW_DOCUMENT_FRAGMENT);
@@ -2444,6 +2900,13 @@
                 }
             }
         }
+        /**
+         * 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;
@@ -2466,6 +2929,7 @@
                 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) {
             /*if (/^\s*\{\s*binding\s+.*\}\s*$/.test(attr)) {
 
@@ -2485,6 +2949,7 @@
             else*/
             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);
@@ -2493,6 +2958,13 @@
                 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) {
             // loose syntax {{ ... }}
             let expression = CustomElementUtils.extractBindingAttributeExpression(attr);
@@ -2513,6 +2985,14 @@
             });
             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 != undefined)
@@ -2573,6 +3053,7 @@
     const GET_VAL$6 = CustomElementUtils.getAttachedPropertyValue;
     const SET_VAL$5 = CustomElementUtils.setAttachedPropertyValue;
     const REPEATERITEM_PLACEHOLDER = 'pacem:repeater-item';
+    /** Static lookup helpers for locating the {@link RepeaterItem} context a given element belongs to. */
     class Repeater {
         /**
          * Seeks for a PacemRepeaterItem element upwards through the DOM tree, given a starting element and the number of nesting levels.
@@ -2587,7 +3068,22 @@
             return retval;
         }
     }
+    /**
+     * 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}.
+     */
     let RepeaterItem$1 = 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) {
                 return null;
@@ -2600,16 +3096,20 @@
             }
             return item;
         }
+        /** Tests whether `node` is the placeholder of some {@link RepeaterItem}. */
         static isRepeaterItem(node) {
             return !Utils.isNull(GET_VAL$6(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$6(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$5(_placeholder, REPEATERITEM_PLACEHOLDER, this);
         }
+        /** The DOM placeholder node standing in for this repetition. */
         get placeholder() {
             return this._placeholder;
         }
@@ -2655,32 +3155,53 @@
     // * ...
     // */
     //const purePropertyPathPattern = /^[\w\.\$]+/; 
+    /**
+     * 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.
+     */
     class Expression {
         constructor() {
             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) {
@@ -2689,6 +3210,12 @@
             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];
@@ -2713,6 +3240,15 @@
             }
             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 };
@@ -2843,13 +3379,20 @@
     // }
 
     //namespace Pacem.Logging {
+    /** Severity levels accepted by {@link Logger.log}, and used by {@link PacemEventTarget.log}. */
     var LogLevel;
     (function (LogLevel) {
+        /** Fine-grained diagnostic detail. */
         LogLevel["Trace"] = "trace";
+        /** Development-time diagnostic detail. */
         LogLevel["Debug"] = "debug";
+        /** Recoverable but noteworthy condition. */
         LogLevel["Warn"] = "warn";
+        /** Unrecoverable or unexpected failure. */
         LogLevel["Error"] = "error";
+        /** General informational message. */
         LogLevel["Info"] = "info";
+        /** Generic/default-severity message. */
         LogLevel["Log"] = "log";
     })(LogLevel || (LogLevel = {}));
     //}
@@ -2903,6 +3446,11 @@
         convert: (attr) => pacemFoundation.Rect.parse(attr),
         convertBack: (prop) => `${prop.x || 0} ${prop.y || 0} ${prop.width || 0} ${prop.height || 0}`
     };
+    /**
+     * 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.
+     */
     const PropertyConverters /*: { [name: string]: PropertyConverter }*/ = {
         None: NonePropertyConverter,
         String: StringPropertyConverter,
@@ -3050,6 +3598,31 @@
         }
         return promises;
     }
+    /**
+     * 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.
+     */
     const CustomElement = (config) => {
         return (target) => {
             // might be already registered
@@ -3384,6 +3957,27 @@
     // #endregion
     // #region WATCH PROPERTIES
     const DefaultPropertyConverter = PropertyConverters.None;
+    /**
+     * 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.
+     */
     function Watch(config) {
         return (target, prop, descriptor) => {
             var watchableProperties = GET_VAL$5(target.constructor, WATCH_PROPS_VAR, []);
@@ -3502,6 +4096,17 @@
             }
         };
     }
+    /**
+     * 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).
+     */
     function ViewChild(selector) {
         return (target, prop, descriptor) => {
             const key = `${prop}_${Utils.uniqueCode()}`;
@@ -3534,6 +4139,15 @@
     }
     // #endregion
     // #region CONCURRENT/DEBOUNCE EXECUTION
+    /**
+     * 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.
+     */
     function Concurrent() {
         function isPromiseLike(obj) {
             return obj && typeof obj.then === 'function';
@@ -3584,6 +4198,15 @@
             };
         };
     }
+    /**
+     * 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.
+     */
     function Debounce(msecs = 50, keyFactory = (key, ...args) => `pacem:debouncer:${key}`) {
         return function (target /* type, actually */, key, descriptor) {
             const originalMethod = descriptor.value;
@@ -3609,6 +4232,16 @@
             }
         };
     }
+    /**
+     * 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.
+     */
     function Throttle(msecs = 50, keyFactory = (key, ...args) => `pacem:throttler:${key}`) {
         return function (target /* type, actually */, key, descriptor) {
             const originalMethod = descriptor.value;
@@ -3658,6 +4291,14 @@
             }
         }
     };
+    /**
+     * 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.
+     */
     function Transformer(name) {
         return function (target, key, descriptor) {
             const method = descriptor.value;
@@ -3675,6 +4316,16 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /**
+     * 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.
+     */
     class PacemEventTarget extends HTMLElement {
         constructor() {
             super();
@@ -3857,12 +4508,14 @@
             return this._aria.attrs;
         }
     }
+    /** Common base class for Pacem custom elements: adds ARIA support, CSS class/part/style bags, visibility, tab order and behaviors. */
     class PacemElement extends PacemEventTarget {
         constructor(role, aria) {
             super();
             this.#cssBag = [];
             this.#parts = [];
             this._tabIndex = -1;
+            /** Gets or sets the list of behaviors to attach to this element. */
             this.behaviors = [];
             this._aria = new ElementAria(this, role, aria);
         }
@@ -4047,6 +4700,7 @@
     __decorate$H([
         Watch({ emit: false })
     ], PacemElement.prototype, "behaviors", void 0);
+    /** Base class for elements whose (sanitized) inner content is driven by a `content` property, restoring the original markup on disconnect. */
     class PacemContentElement extends PacemElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -4090,11 +4744,13 @@
     __decorate$H([
         Watch({ emit: false, converter: PropertyConverters.String })
     ], PacemContentElement.prototype, "content", void 0);
+    /** {@link PacemContentElement} variant that renders `content` verbatim, without any sanitization. */
     class PacemUnsafeContentElement extends PacemContentElement {
         sanitize(html) {
             return html;
         }
     }
+    /** {@link PacemContentElement} variant that strips out `<script>` blocks (and, for `Node` content, `<script>` elements) before rendering `content`. */
     class PacemSafeContentElement extends PacemContentElement {
         _sanitizeLegacy(html) {
             if (Utils.isNullOrEmpty(html)) {
@@ -4126,6 +4782,7 @@
     }
     //}
 
+    /** Base class for pluggable adapters that drive the focus/navigation behavior of a {@link PacemIterativeElement}. */
     class PacemAdapter extends PacemElement {
         constructor() {
             super(...arguments);
@@ -4254,6 +4911,10 @@
             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);
         }
@@ -4277,6 +4938,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Removes itself from the DOM as soon as it gets connected; handy to strip out placeholder markup at runtime. */
     let PacemAnnihilatorElement = class PacemAnnihilatorElement extends HTMLElement {
         constructor() {
             super();
@@ -4297,6 +4959,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Warns the user (native `beforeunload` prompt or router-driven confirm dialog) before leaving the page. */
     let PacemBeforeunloadElement = class PacemBeforeunloadElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -4343,9 +5006,11 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Wraps a {@link BroadcastChannel}, sending/receiving messages to/from other same-origin browsing contexts. */
     let PacemBroadcastChannelProxyElement = class PacemBroadcastChannelProxyElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
+            /** Gets or sets whether to automatically send `message` as soon as it changes (default `true`). */
             this.autosend = true;
             this._messageHandler = (evt) => {
                 this.result = evt.data;
@@ -4381,6 +5046,10 @@
             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;
@@ -4433,6 +5102,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Detects the name and version of the current (or a provided) browser user agent. */
     let PacemBrowserDetectElement = class PacemBrowserDetectElement extends PacemEventTarget {
         viewActivatedCallback() {
             super.viewActivatedCallback();
@@ -4446,9 +5116,11 @@
         }
         #browser;
         #version;
+        /** @readonly Gets the detected browser name. */
         get browser() {
             return this.#browser;
         }
+        /** @readonly Gets the detected browser version. */
         get version() {
             return this.#version;
         }
@@ -4475,6 +5147,12 @@
 
     //namespace Pacem {
     const EXPIRATION_FIELD = '_exp';
+    /**
+     * 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.
+     */
     class Storage {
         _getStorage(persistent) {
             return !!persistent ? window.localStorage : window.sessionStorage;
@@ -4509,10 +5187,16 @@
             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();
@@ -4520,6 +5204,7 @@
             storage.clear();
         }
         ;
+        /** Removes a single entry by `name` from both session and local storage. */
         removeProperty(name) {
             var storage = this._getStorage(true);
             storage.removeItem(name);
@@ -4536,6 +5221,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Holds an arbitrary data model, optionally persisting it to local storage and debouncing/throttling change notifications. */
     let PacemDataElement = class PacemDataElement extends PacemEventTarget {
         constructor(storage = new Storage()) {
             super();
@@ -4731,6 +5417,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Base class for elements that move their own content to another DOM location, restoring nothing on disconnect. */
     class PacemTransferProxyElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -4836,6 +5523,7 @@
             return PropertyConverters.Element.convertBack(prop, element);
         }
     };
+    /** Listens for an arbitrary DOM event on a `target` element (or `window`) and re-dispatches it as its own `emit` event. */
     let PacemEventProxyElement = class PacemEventProxyElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -4908,11 +5596,13 @@
     };
     //namespace Pacem.Components {
     const ABORT_MESSAGE = "New incoming request overrides the ongoing one. Aborting.";
+    /** Declarative wrapper around the `fetch()` API, debouncing/aborting requests as its properties change and exposing the parsed `result`. */
     let PacemFetchElement = class PacemFetchElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
             /** Gets or sets whether to trigger a fetch whenever a significant property has changed (default: true). */
             this.autofetch = true;
+            /** Gets or sets the debounce delay (in milliseconds) applied before auto-triggered fetches (default `100`). */
             this.debounce = 100;
         }
         viewActivatedCallback() {
@@ -5171,6 +5861,7 @@
             super(type, { detail });
         }
     }
+    /** Keeps track of an undo/redo-capable history of an arbitrary state. */
     let PacemHistoryElement = class PacemHistoryElement extends PacemEventTarget {
         #history;
         propertyChangedCallback(name, old, val, first) {
@@ -5204,6 +5895,7 @@
                 this.#history = new pacemFoundation.HistoryService(val, this.maxlength);
             }
         }
+        /** Moves the state forward one step, if `canRedo` is `true`. */
         redo() {
             const h = this.#history;
             if (!Utils.isNull(h)) {
@@ -5212,6 +5904,7 @@
                 this._synchronize('redo');
             }
         }
+        /** Clears the history stack, keeping only the current state. */
         reset() {
             const h = this.#history;
             if (!Utils.isNull(h)) {
@@ -5220,6 +5913,7 @@
                 this._synchronize('reset');
             }
         }
+        /** Moves the state back one step, if `canUndo` is `true`. */
         undo() {
             const h = this.#history;
             if (!Utils.isNull(h)) {
@@ -5261,6 +5955,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Sets (or removes) an attribute on the document's root `<html>` element. */
     let PacemHtmlProxyElement = class PacemHtmlProxyElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -5309,6 +6004,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Conditionally shows or clears its own inner content, restoring the original markup whenever `match` becomes truthy again. */
     let PacemIfElement = class PacemIfElement extends HTMLElement {
         #innerHTML;
         propertyChangedCallback(name, old, val, first) {
@@ -5339,6 +6035,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Base class for elements that register themselves against an ancestor {@link PacemItemsContainerElement}. */
     class PacemItemElement extends PacemElement {
         get container() {
             return this._container;
@@ -5444,6 +6141,7 @@
     __decorate$u([
         Watch( /* can only be databound or assigned at runtime */)
     ], PacemCrossItemsContainerElement.prototype, "items", void 0);
+    /** Base class for container elements holding a registry of {@link PacemItemElement} children. */
     class PacemItemsContainerElement extends PacemElement {
         constructor(role, aria) {
             super(role, aria);
@@ -5476,6 +6174,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Base class for items belonging to a {@link PacemIterativeElement}, forwarding their property changes to the master's `adapter`. */
     class PacemIterableElement extends PacemItemElement {
         /** @overrides */
         findContainer() {
@@ -5491,6 +6190,7 @@
                 && iter.adapter.itemPropertyChangedCallback(index, name, old, val, first);
         }
     }
+    /** Base class for container elements whose items are driven by a pluggable {@link PacemAdapter}, tracking a `current` `index`. */
     class PacemIterativeElement extends PacemItemsContainerElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -5548,6 +6248,7 @@
     //namespace Pacem.Components {
     const REMOVE_VALUE = 'false';
     const EMPTY_VALUE = 'true';
+    /** Sets (or removes) an attribute on the closest ancestor shell element, e.g. to drive layout-wide CSS state. */
     let PacemLayoutProxyElement = class PacemLayoutProxyElement extends PacemEventTarget {
         #shell;
         connectedCallback() {
@@ -5601,6 +6302,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Creates, updates or removes a `<meta>` element in the document `<head>`, keyed by either `name` or `itemprop`. */
     let PacemMetaProxyElement = class PacemMetaProxyElement extends PacemEventTarget {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -5662,6 +6364,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Tracks the browser's network connectivity (`navigator.onLine`), updating `online` on `online`/`offline` events. */
     let PacemOnlineStatusElement = class PacemOnlineStatusElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -5704,6 +6407,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Plain generic-purpose container element, useful as a databinding/behaviors host wherever a `<div>` would do. */
     let PacemPanelElement = class PacemPanelElement extends PacemSafeContentElement {
     };
     PacemPanelElement = __decorate$p([
@@ -5713,7 +6417,12 @@
 
     /// <reference path="events.ts" />
     //namespace Pacem {
+    /** Event name dispatched to signal a generic, named command invocation; see {@link CommandEvent}. */
     const CommandEventName = 'command';
+    /**
+     * 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.
+     */
     class CommandEvent extends CustomTypedEvent {
         constructor(args) {
             super(CommandEventName, args, { bubbles: true, cancelable: true });
@@ -5728,6 +6437,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Redirects consumers (e.g. {@link PacemRepeaterElement}) to an external `<template>` element, firing a `templatechange` event when it changes. */
     let PacemTemplateProxyElement = class PacemTemplateProxyElement extends /*PacemEventTarget*/ /*PacemEventTarget*/ TemplateElement {
         propertyChangedCallback(name, old, val, first) {
             // super.propertyChangedCallback(name, old, val, first);
@@ -5782,6 +6492,8 @@
     }
     //
     /**
+     * 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>
@@ -5813,6 +6525,7 @@
                 this._databind();
             };
         }
+        /** Removes the rendered item at the given index. */
         removeItem(index) {
             this._removeItems(index, index);
         }
@@ -5841,6 +6554,7 @@
                 item.remove();
             }
         }
+        /** Forces a full re-render of the items against the current `datasource`. */
         databind() {
             this._databind();
         }
@@ -6038,6 +6752,7 @@
         }
     }
     const BORDER_BOX = { box: 'border-box' };
+    /** Observes size (and, optionally, position) changes of itself or a `target` element, firing a `resize` event accordingly. */
     let PacemResizeElement = class PacemResizeElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -6136,6 +6851,7 @@
                 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) {
@@ -6175,6 +6891,7 @@
     };
     //namespace Pacem.Components {
     const CHECK_PATTERN = /^([\w\.]:)?\/\/[^\/]+/;
+    /** Client-side router: parses/generates paths against a template and drives the browser History API. */
     let PacemRouterElement = class PacemRouterElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -6196,6 +6913,10 @@
         }
         #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);
@@ -6455,6 +7176,7 @@
         }
         return output;
     }
+    /** Registers a service worker and manages its (optional) Push API subscription. */
     let PacemServiceWorkerProxyElement = class PacemServiceWorkerProxyElement extends PacemEventTarget {
         viewActivatedCallback() {
             super.viewActivatedCallback();
@@ -6507,6 +7229,10 @@
                 }
             });
         }
+        /**
+         * 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)) {
@@ -6524,6 +7250,10 @@
                 }
             });
         }
+        /**
+         * 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') {
@@ -6611,6 +7341,7 @@
             || (/^arrow/.test(key) && (piece === key.substr(5)));
     }
     const KeyboardShortcutExecuteEventName = "execute";
+    /** Listens for a keyboard shortcut (optionally chorded, e.g. `"ctrl+k, s"`) on a target and fires an `execute` event when matched. */
     let PacemShortcutElement = class PacemShortcutElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -6668,6 +7399,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Sets its own `textContent` to the `text` property, escaping any markup. */
     let PacemSpanElement = class PacemSpanElement extends PacemSafeContentElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -6697,6 +7429,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Injects a `<style>` element into the document `<head>`, populated either inline (`cssText`) or by fetching `src`. */
     let PacemStyleProxyElement = class PacemStyleProxyElement extends PacemEventTarget {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -6797,6 +7530,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Renders the `text` property as its own plain-text content, replacing any existing child markup. */
     let PacemTextElement = class PacemTextElement extends HTMLElement {
         constructor() {
             super();
@@ -6828,6 +7562,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Fires a `tick` event on a regular interval, as long as it's enabled and `interval` is greater than zero. */
     let PacemTimerElement = class PacemTimerElement extends PacemEventTarget {
         constructor() {
             super();
@@ -6874,6 +7609,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Sets `document.title` to `value` whenever it changes. */
     let PacemTitleProxyElement = class PacemTitleProxyElement extends PacemEventTarget {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -6909,10 +7645,12 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Animates a numeric `value` from `from` to `to` over `duration`, dispatching animation lifecycle events along the way. */
     let PacemTweenElement = class PacemTweenElement extends PacemEventTarget {
         constructor(_tweener = new TweenService()) {
             super();
             this._tweener = _tweener;
+            /** Gets or sets the animation duration, in milliseconds (default `1000`). */
             this.duration = 1000;
         }
         propertyChangedCallback(name, old, val, first) {
@@ -6922,6 +7660,7 @@
                     this._animate();
             }
         }
+        /** Starts the animation programmatically and returns a promise resolved once it completes. */
         run() {
             return this._animate();
         }
@@ -7071,9 +7810,11 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /** Wraps a {@link Worker}, sending/receiving messages to/from a web worker script. */
     let PacemWebWorkerProxyElement = class PacemWebWorkerProxyElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
+            /** Gets or sets whether to automatically send `message` as soon as it changes (default `true`). */
             this.autosend = true;
             this._messageHandler = (evt) => {
                 this.result = evt.data;
@@ -7109,6 +7850,10 @@
             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;
@@ -7154,8 +7899,16 @@
     //}
 
     //namespace Pacem.Behaviors{
+    /**
+    * 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.
+    */
     class PacemBehavior extends PacemEventTarget {
         #items = 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)) {
@@ -7163,6 +7916,10 @@
                 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)) {
@@ -7170,6 +7927,7 @@
                 container.delete(element);
             }
         }
+        /** @readonly Determines whether the given element is currently registered with this behavior. */
         has(element) {
             return this.#items.has(element);
         }
@@ -7591,7 +8349,8 @@
         }
     }
     /**
-     * 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}.
      */
     let PacemDragDropElement = class PacemDragDropElement extends PacemBehavior {
         constructor() {
@@ -7655,23 +8414,28 @@
             /** Gets or sets the drag mode ("self", "alias", "copy"). */
             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 };
             // TODO: add special effects starting the drag process after a while (timeout) the element is pressed. 
             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_VAL$3(evt.detail.element, MOUSE_DOWN$2);
@@ -7854,6 +8618,10 @@
     const RESCALE_FRAME = 'pacem:rescale:frame';
     const MOUSE_DOWN$1 = 'pacem:rescale:origin';
     const DELEGATE$1 = 'pacem:rescale:delegate';
+    /**
+     * Pacem Rescale element adapter: implements {@link Rescaler} on top of {@link PacemBehavior}, decorating
+     * registered elements with draggable resize handles (see {@link RescaleHandle}).
+     */
     let PacemRescaleElement = class PacemRescaleElement extends PacemBehavior {
         constructor() {
             super(...arguments);
@@ -7881,11 +8649,13 @@
                 /* logging */ (level, message, category) => this.log.apply(this, [level, message, category])));
             };
         }
+        /** Adds the resize-handle frame (see {@link RescaleHandle}) around the given element. */
         decorate(element) {
             const el = element; 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');
@@ -8069,6 +8839,10 @@
             return x;
         }
     }
+    /**
+     * 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.
+     */
     let PacemRotateElement = class PacemRotateElement extends PacemBehavior {
         constructor() {
             super(...arguments);
@@ -8106,6 +8880,7 @@
                 /* logging */ (level, message, category) => this.log.apply(this, [level, message, category])));
             };
         }
+        /** 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');
@@ -8113,6 +8888,7 @@
             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');
@@ -8344,6 +9120,10 @@
             window.removeEventListener('pointerup', this._endHandler);
         }
     }
+    /**
+     * 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.
+     */
     let PacemSwipeElement = class PacemSwipeElement extends PacemBehavior {
         constructor() {
             super(...arguments);
@@ -8396,6 +9176,7 @@
                 this._undo(el);
             };
         }
+        /** Wires up the `pointerdown` listener that arms the swipe gesture on the given element. */
         decorate(element) {
             // https://docs.microsoft.com/en-us/microsoft-edge/dev-guide/dom/pointer-events
             if (element instanceof HTMLElement || element instanceof SVGElement) {
@@ -8403,6 +9184,7 @@
             }
             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');
@@ -8467,6 +9249,10 @@
     const EasingConverter = {
         convert: (attr) => Easings[attr] ?? Easings.linear
     };
+    /**
+    * Abstract base class for the `@CustomElement` animation items (color/number/point animations) that can be
+    * hosted within a {@link PacemStoryboardElement}. Implements {@link Timeline}.
+    */
     class AnimationElement extends PacemItemElement {
     }
     __decorate$5([
@@ -8490,15 +9276,21 @@
     __decorate$5([
         Watch({ emit: false, converter: PropertyConverters.String })
     ], AnimationElement.prototype, "direction", void 0);
+    /**
+    * 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`.
+    */
     class TweenAnimationElement extends AnimationElement {
         constructor(_tweener = new TweenService()) {
             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, _) => {
@@ -8511,6 +9303,7 @@
                     .then(resolve);
             });
         }
+        /** Cancels the running tween. */
         cancelAnimation() {
             this.#cancelToken = true;
         }
@@ -8525,6 +9318,7 @@
     //namespace Pacem.Components {
     const DEFAULT_FROM$2 = { h: 0, l: 0, s: 0.5, a: 1 };
     const DEFAULT_TO$2 = { h: 0, l: 1, s: 0.5, a: 1 };
+    /** Animates a CSS color `target[property]` from `from` to `to` (interpolated in HSLA space) over `duration`. */
     let PacemColorAnimationElement = class PacemColorAnimationElement extends TweenAnimationElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -8568,6 +9362,7 @@
         _parseColor(clr) {
             return pacemFoundation.Colors.hsl(pacemFoundation.Colors.parse(clr));
         }
+        /** @inheritdoc */
         tweenInterpolationCallback(time, progress) {
             const from = this.#from, to = this.#to;
             const hsla = {
@@ -8598,7 +9393,9 @@
     //namespace Pacem.Components {
     const DEFAULT_FROM$1 = 0;
     const DEFAULT_TO$1 = 1;
+    /** Animates a numeric `target[property]` from `from` to `to` over `duration`. */
     let PacemNumberAnimationElement = class PacemNumberAnimationElement extends TweenAnimationElement {
+        /** @inheritdoc */
         tweenInterpolationCallback(time, progress) {
             const to = this.to ?? DEFAULT_TO$1, from = this.from ?? DEFAULT_FROM$1;
             return (to - from) * progress + from;
@@ -8623,7 +9420,9 @@
     //namespace Pacem.Components {
     const DEFAULT_FROM = { x: 0, y: 0 };
     const DEFAULT_TO = { x: 1, y: 1 };
+    /** Animates a {@link Point} `target[property]` from `from` to `to` over `duration`. */
     let PacemPointAnimationElement = class PacemPointAnimationElement extends TweenAnimationElement {
+        /** @inheritdoc */
         tweenInterpolationCallback(time, progress) {
             const to = this.to ?? DEFAULT_TO, from = this.from ?? DEFAULT_FROM;
             return {
@@ -8650,7 +9449,12 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components {
+    /**
+     * 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`.
+     */
     let PacemStoryboardElement = class PacemStoryboardElement extends PacemItemsContainerElement {
+        /** @inheritdoc */
         validate(item) {
             return item instanceof AnimationElement;
         }
@@ -8691,12 +9495,14 @@
             }
             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);
         }
@@ -8806,13 +9612,16 @@
     });
 
     //namespace Pacem {
+    /** Framework-wide default settings. */
     const Defaults = {
         USE_SHADOW_ROOT: /*'attachShadow' in Element.prototype &&*/ false /* <- wait until html-imports */
     };
     //}
 
     //namespace Pacem.RegularExpressions {
+    /** A pattern that can never match any string (`/a^/`); useful as a safe no-op default for optional matcher parameters. */
     const EMPTY_MATCHER = /a^/;
+    /** Static regular-expression helpers. */
     class Regex {
         /**
          * Splits an input string into segments based on a matching pattern.
@@ -8868,7 +9677,21 @@
             cssRemove: cssRemove ?? 'fill-red-container',
         };
     }
+    /**
+     * The framework's built-in library of template-expression transform functions. Each static method here
+     * is registered, via the {@link Transformer} decorator, under `Utils.core` (mostly by its own method
+     * name - see each method's `@Transformer(...)` name override where present) so it becomes callable by
+     * name from binding expressions (e.g. `{{ ^value | size }}`). Not part of the module's exported surface -
+     * consumers use these by their registered transform name, not by importing this class.
+     */
     class Transforms {
+        /**
+         * 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;
@@ -8911,9 +9734,11 @@
                 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) {
             // TODO: use logarithms
             if (!(src > 0))
@@ -8926,12 +9751,25 @@
                 return (src / 1_048_576).toFixed(2) + ' MB';
             return (src / 1_073_741_824).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 = '° ', 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') {
@@ -8959,6 +9797,13 @@
                 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') {
@@ -8969,18 +9814,26 @@
             const msecsPerDay = 86400000, msecsPerHr = 3600000, msecsPerMin = 60000, days = Math.floor(elapsed / msecsPerDay), hrs = Math.floor((elapsed % msecsPerDay) / msecsPerHr), mins = Math.floor((elapsed % msecsPerHr) / msecsPerMin), secs = Math.floor((elapsed % msecsPerMin) / 1000), msecs = Math.floor(elapsed % 1000);
             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: 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)) {
@@ -8991,31 +9844,39 @@
             });
         }
         // #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(obj) {
             return Utils.isEmpty(obj);
         }
+        /** Template-expression shortcut for {@link Utils.isNull}. */
         static isNull(obj) {
             return Utils.isNull(obj);
         }
+        /** Template-expression shortcut for {@link Utils.isNullOrEmpty}. */
         static isNullOrEmpty(obj) {
             return Utils.isNullOrEmpty(obj);
         }
+        /** 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);
         }