@pacem/pacem-core 2.0.0-goldbach → 2.0.0-hadamard

package/dist/browser/pacem-core.js

@@ -1,5 +1,5 @@
 /*!
- * @pacem/pacem-core v2.0.0-goldbach (https://js.pacem.it)
+ * @pacem/pacem-core v2.0.0-hadamard (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
@@ -409,7 +409,7 @@
             },
             /** Sets a CSS custom property's value on the document root (`:root`/`html`). */
             setVariable(name, value) {
-                getComputedStyle(document.documentElement).setProperty(name, value);
+                document.documentElement.style.setProperty(name, value);
             },
             /**
              * Naive O(n^2) implementation for an actual css class presence (definition) in the current DOM.
@@ -1555,12 +1555,12 @@
          * Parses a binding expression against a scope.
          * @param expression The bare expression text (no `{{ }}` delimiters, no `, twoway`/`, once` modifier).
          * @param scope What the references resolve to.
-         * @throws When the expression is unsafe (see {@link analyze}).
+         * @throws An `Error` when the expression is unsafe (see {@link analyze}).
          */
         static parse(expression, scope) {
             const analysis = BindingParser.analyze(expression);
             if (analysis.unsafe != null) {
-                throw `Unsafe expression detected: "${analysis.unsafe}" in "${expression}".`;
+                throw new Error(`Unsafe expression detected: "${analysis.unsafe}" in "${expression}".`);
             }
             if (!analysis.hasReferences) {
                 return { kind: 'constant', functionBody: `return ${expression};`, voidBody: expression, dependencies: [] };
@@ -5009,6 +5009,14 @@
         get element() {
             return this._builder.element;
         }
+        /**
+         * @readonly Gets the snap the element is going to rest at, relative to where the gesture started: `0` means it
+         * bounces back home (the release didn't make it). Known on release (`swipe`, `swipe<direction>` and the
+         * animation-end events); `undefined` while panning.
+         */
+        get snap() {
+            return this._builder.snap;
+        }
         /** Builds a new {@link SwipeEventArgsClass} out of a plain {@link SwipeEventArgs} builder. */
         static fromArgs(builder) {
             return new SwipeEventArgsClass(Utils.extend({}, builder));
@@ -5402,34 +5410,58 @@
             return html;
         }
     }
-    /** {@link PacemContentElement} variant that strips out `<script>` blocks (and, for `Node` content, `<script>` elements) before rendering `content`. */
+    /** Attributes holding a URL, checked for `javascript:` ones by {@link sanitizeNode}. */
+    const URL_ATTRIBUTES = ['href', 'src', 'action', 'formaction', 'xlink:href'];
+    /** Whether an attribute value is a `javascript:` URL (whitespace and control characters ignored, as browsers do). */
+    function isScriptUrl(value) {
+        const normalized = (value ?? '').replace(/[\u0000- ]/g, '').toLowerCase();
+        return normalized.startsWith('javascript:');
+    }
+    /**
+     * Strips the script-capable parts of a DOM subtree, in place: `<script>` elements, `on*` event-handler attributes,
+     * `javascript:` URLs.
+     * @param node The subtree's root.
+     */
+    function sanitizeNode(node) {
+        for (let i = node.childNodes.length - 1; i >= 0; i--) {
+            const child = node.childNodes.item(i);
+            if (child instanceof Element && child.localName === 'script') {
+                child.remove();
+                continue;
+            }
+            sanitizeNode(child);
+        }
+        if (!(node instanceof Element)) {
+            return;
+        }
+        for (const attribute of Array.from(node.attributes)) {
+            const name = attribute.name.toLowerCase();
+            const isHandler = name.startsWith('on');
+            const isScriptLink = URL_ATTRIBUTES.indexOf(name) >= 0 && isScriptUrl(attribute.value);
+            if (isHandler || isScriptLink) {
+                node.removeAttribute(attribute.name);
+            }
+        }
+    }
+    /**
+     * {@link PacemContentElement} variant that renders `content` without what could run script: `<script>` elements,
+     * `on*` event-handler attributes and `javascript:` URLs get removed (HTML strings are parsed, never executed, first).
+     */
     class PacemSafeContentElement extends PacemContentElement {
-        _sanitizeLegacy(html) {
+        sanitize(html) {
             if (Utils.isNullOrEmpty(html)) {
                 return html;
             }
             if (html instanceof Node) {
-                for (let i = html.childNodes.length - 1; i >= 0; i--) {
-                    const node = html.childNodes.item(i);
-                    if (node instanceof HTMLScriptElement) {
-                        node.remove();
-                    }
-                    else {
-                        this.sanitize(node);
-                    }
-                }
+                sanitizeNode(html);
                 return html;
             }
-            else {
-                const scriptBlockPattern = /<script.+<\/script>/g;
-                // TODO: remove onclick, onload, onkey*, ... attributes
-                return (html || '').toString().replace(scriptBlockPattern, '');
-            }
-        }
-        sanitize(html) {
-            // TODO: implement by using (when available in dom library)
-            // https://developer.mozilla.org/en-US/docs/Web/API/Sanitizer/Sanitizer
-            return this._sanitizeLegacy(html);
+            // a template parses without running anything (scripts, image loads with their handlers…)
+            const template = document.createElement('template');
+            template.innerHTML = html.toString();
+            const fragment = template.content;
+            sanitizeNode(fragment);
+            return fragment;
         }
     }
     //}
@@ -5658,7 +5690,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. */
+    /**
+     * Wraps a {@link BroadcastChannel}, sending/receiving messages to/from other same-origin browsing contexts.
+     * @fires receive {@link CustomEvent} - when a message arrives from another channel of the same name: `detail` is the message (also in `result`).
+     * @fires error {@link CustomEvent} - when an arrived message couldn't be deserialized.
+     */
     let PacemBroadcastChannelProxyElement = class PacemBroadcastChannelProxyElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -5680,7 +5716,7 @@
             super.propertyChangedCallback(name, old, val, first);
             if (!first) {
                 switch (name) {
-                    case 'src':
+                    case 'channelName':
                         this._disposeChannel();
                         this._initializeChannel(val);
                         break;
@@ -5728,6 +5764,10 @@
                 channel.removeEventListener('message', this._messageHandler, false);
                 channel.close();
             }
+            // (a closed channel can't post anymore)
+            if (channel === this.#channel) {
+                this.#channel = null;
+            }
         }
     };
     __decorate$D([
@@ -5804,13 +5844,32 @@
         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. */
+    /** Converts the `debounce` attribute: `true`/`false`, or else a number of milliseconds. */
+    const DebouncePropertyConverter = {
+        convert: (attr) => {
+            switch (attr) {
+                case 'true':
+                    return true;
+                case 'false':
+                    return false;
+                default:
+                    return parseFloat(attr);
+            }
+        },
+        convertBack: (prop) => `${prop}`
+    };
+    /**
+     * Holds an arbitrary data model, optionally persisting it to local storage and debouncing/throttling change notifications.
+     * @fires propertychange {@link PropertyChangeEvent} - when `model` changes (debounced or throttled as set by `debounce` and `throttle`).
+     */
     let PacemDataElement = class PacemDataElement extends PacemEventTarget {
         constructor(storage = new Storage()) {
             super();
             this.storage = storage;
-            this._handle = 0;
-            this._flag = false;
+            /** Cancels the pending (debounced) notification, if any. */
+            this._cancelPending = null;
+            /** Whether a throttling window is open (changes are dropped meanwhile). */
+            this._throttling = false;
         }
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -5824,35 +5883,63 @@
                     }
                     break;
                 case 'model':
-                    const debounce = this.debounce, throttle = this.throttle, emit = () => {
-                        this.dispatchEvent(new PropertyChangeEvent({ propertyName: name, oldValue: old, currentValue: val, firstChange: first }));
-                    };
-                    if (debounce > 0 && !first) {
-                        if (throttle) {
-                            if (this._flag)
-                                return;
-                            this._flag = true;
-                            emit();
-                            this._handle = window.setTimeout(() => { this._flag = false; }, debounce);
-                        }
-                        else {
-                            clearTimeout(this._handle);
-                            this._handle = window.setTimeout(emit, debounce);
-                        }
-                    }
-                    else {
-                        emit();
-                    }
-                    // persist
-                    if (!first && !Utils.isNullOrEmpty(this.persistAs)) {
-                        if (Utils.isNull(val))
-                            this.storage.removeProperty(this.persistAs);
-                        else
-                            this.storage.setPropertyValue(this.persistAs, val, true);
-                    }
+                    this._notifyModelChange(old, val, first);
+                    this._persist(val, first);
                     break;
             }
         }
+        /** Notifies a model change: right away, debounced or throttled (see {@link debounce} and {@link throttle}). */
+        _notifyModelChange(old, val, first) {
+            const emit = () => {
+                this.dispatchEvent(new PropertyChangeEvent({ propertyName: 'model', oldValue: old, currentValue: val, firstChange: first }));
+            };
+            const debounce = this.debounce;
+            const perFrame = debounce === true;
+            const delay = typeof debounce === 'number' && debounce > 0 ? debounce : 0;
+            if (first || (!perFrame && delay === 0)) {
+                emit();
+                return;
+            }
+            if (this.throttle) {
+                this._throttle(emit, perFrame, delay);
+                return;
+            }
+            this._cancelPending?.();
+            this._cancelPending = this._schedule(emit, perFrame, delay);
+        }
+        /** Notifies the first change of a window, and drops the others until the window closes. */
+        _throttle(emit, perFrame, delay) {
+            if (this._throttling) {
+                return;
+            }
+            this._throttling = true;
+            emit();
+            this._schedule(() => { this._throttling = false; }, perFrame, delay);
+        }
+        /**
+         * Runs a callback on the next animation frame, or after a delay.
+         * @returns A function cancelling it.
+         */
+        _schedule(callback, perFrame, delay) {
+            if (perFrame) {
+                const frame = requestAnimationFrame(callback);
+                return () => cancelAnimationFrame(frame);
+            }
+            const timeout = window.setTimeout(callback, delay);
+            return () => clearTimeout(timeout);
+        }
+        /** Persists the model under {@link persistAs}, if set (a `null` model removes it). */
+        _persist(val, first) {
+            const key = this.persistAs;
+            if (first || Utils.isNullOrEmpty(key)) {
+                return;
+            }
+            if (Utils.isNull(val)) {
+                this.storage.removeProperty(key);
+                return;
+            }
+            this.storage.setPropertyValue(key, val, true);
+        }
     };
     __decorate$B([
         Watch({ emit: false /* in order to debounce the propertychange emit */, converter: PropertyConverters.Eval })
@@ -5861,7 +5948,7 @@
         Watch({ emit: false, converter: PropertyConverters.String })
     ], PacemDataElement.prototype, "persistAs", void 0);
     __decorate$B([
-        Watch({ emit: false, converter: PropertyConverters.Number })
+        Watch({ emit: false, converter: DebouncePropertyConverter })
     ], PacemDataElement.prototype, "debounce", void 0);
     __decorate$B([
         Watch({ emit: false, converter: PropertyConverters.BooleanStrict })
@@ -6106,7 +6193,10 @@
             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. */
+    /**
+     * Listens for an arbitrary DOM event on a `target` element (or `window`) and re-dispatches it as its own `emit` event.
+     * @fires emit {@link Event} - for every `event` caught on `target`: the caught one is `originalEvent`.
+     */
     let PacemEventProxyElement = class PacemEventProxyElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -6179,7 +6269,12 @@
     };
     //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`. */
+    /**
+     * Declarative wrapper around the `fetch()` API, debouncing/aborting requests as its properties change and exposing the parsed `result`.
+     * @fires success {@link CustomEvent} - when a response is OK (2xx), before its body gets parsed: `detail` is the `Response`.
+     * @fires fetchresult {@link CustomEvent} - when the body got parsed (as set by `as`): `detail` is the new `result`.
+     * @fires error {@link CustomEvent} - when a response is not OK: `detail` is the `Response` (network failures reject `fetch()` instead).
+     */
     let PacemFetchElement = class PacemFetchElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -6447,7 +6542,7 @@
         Watch({ reflectBack: true, converter: PropertyConverters.Number })
     ], PacemFetchElement.prototype, "debounce", void 0);
     __decorate$x([
-        Watch({ emit: false, reflectBack: true, converter: PropertyConverters.Number })
+        Watch({ emit: false, reflectBack: true, converter: PropertyConverters.Boolean })
     ], PacemFetchElement.prototype, "throttle", void 0);
     __decorate$x([
         Watch({ emit: false, reflectBack: true, converter: PropertyConverters.Boolean })
@@ -6471,7 +6566,13 @@
             super(type, { detail });
         }
     }
-    /** Keeps track of an undo/redo-capable history of an arbitrary state. */
+    /**
+     * Keeps track of an undo/redo-capable history of an arbitrary state.
+     * @fires push {@link StateEvent} - when a new state got recorded: `detail` has `state`, `canUndo` and `canRedo`.
+     * @fires undo {@link StateEvent} - after a step back.
+     * @fires redo {@link StateEvent} - after a step forward.
+     * @fires reset {@link StateEvent} - when the history got cleared (the current state stays).
+     */
     let PacemHistoryElement = class PacemHistoryElement extends PacemEventTarget {
         #history;
         propertyChangedCallback(name, old, val, first) {
@@ -6974,7 +7075,10 @@
         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. */
+    /**
+     * Tracks the browser's network connectivity (`navigator.onLine`), updating `online` on `online`/`offline` events.
+     * @fires propertychange {@link PropertyChangeEvent} - when `online` changes (the connection dropped or came back).
+     */
     let PacemOnlineStatusElement = class PacemOnlineStatusElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -7088,6 +7192,10 @@
     //
     /**
      * Repeats its `<template>` content once per `datasource` item, keeping the rendered items in sync as the datasource changes.
+     * @fires repeateritemcreate {@link RepeaterItemCreateEvent} - when an item got rendered (and is in the DOM): `detail` has its `index`, `item` and `dom`.
+     * @fires repeateritemremove {@link RepeaterItemRemoveEvent} - when an item got removed (the datasource shrank).
+     * @fires itemcommand {@link CustomEvent} - when an element of an item dispatches a command (e.g. a `<pacem-button command-name>`): `detail` has `commandName` and `commandArgument`.
+     * @fires item{command} {@link CustomEvent} - right after `itemcommand`, named after the command (e.g. `itemdelete` for `command-name="delete"`): `detail` is the `commandArgument`.
      * @example
      * <pacem-repeater datasource="[{id:'first', items:['a','b','c']}, ...]">
      * <ol>
@@ -7492,7 +7600,12 @@
     };
     //namespace Pacem.Components {
     const CHECK_PATTERN = /^([\w\.]:)?\/\/[^\/]+/;
-    /** Client-side router: parses/generates paths against a template and drives the browser History API. */
+    /**
+     * Client-side router: parses/generates paths against a template and drives the browser History API.
+     * @fires propertychange {@link PropertyChangeEvent} - when `state` changes (every committed navigation).
+     * @fires navigating {@link RouterNavigatingEvent} - on `window`, right before a navigation: cancelable (`preventDefault()` aborts it), `detail` is the target path.
+     * @fires navigate {@link RouterNavigateEvent} - on `window`, once a navigation is committed: `detail` has `path`, `referrer` and `title`.
+     */
     let PacemRouterElement = class PacemRouterElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -7777,7 +7890,13 @@
         }
         return output;
     }
-    /** Registers a service worker and manages its (optional) Push API subscription. */
+    /**
+     * Registers a service worker and manages its (optional) Push API subscription.
+     * @fires register {@link CustomEvent} - once the service worker got registered: `detail` is the `ServiceWorkerRegistration`.
+     * @fires unregister {@link CustomEvent} - when a previous registration got replaced: `detail` is the old one.
+     * @fires subscribe {@link CustomEvent} - when a push subscription is in place (found at start, or just made): `detail` is the `PushSubscription`.
+     * @fires unsubscribe {@link CustomEvent} - when the push subscription went away: `detail` is the old `PushSubscription`.
+     */
     let PacemServiceWorkerProxyElement = class PacemServiceWorkerProxyElement extends PacemEventTarget {
         viewActivatedCallback() {
             super.viewActivatedCallback();
@@ -7844,6 +7963,8 @@
                             this.pushSubscription = null;
                         }
                         resolve(result);
+                    }, reason => {
+                        reject(reason);
                     });
                 }
                 else {
@@ -7854,6 +7975,8 @@
         /**
          * Subscribes to push notifications through the registered service worker.
          * @param publicKey VAPID public key (base64url or raw bytes); defaults to `publicKey`
+         * @returns The subscription (`null` without a push manager, or when notifications are denied); rejects when the
+         * browser refuses to subscribe (no push service, an invalid key…).
          */
         subscribe(publicKey = this.publicKey) {
             return new Promise((resolve, reject) => {
@@ -7872,6 +7995,9 @@
                         else {
                             resolve(/* triggers 'subscribe' event */ this.pushSubscription = subscription);
                         }
+                    }, reason => {
+                        // refused (permission denied, no push service, a bad key…): the caller gets to know
+                        reject(reason);
                     });
                 }
                 else {
@@ -7942,12 +8068,20 @@
             || (/^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. */
+    /**
+     * Listens for a keyboard shortcut (optionally chorded, e.g. `"ctrl+k, s"`) on a target and fires an `execute` event when matched.
+     * @fires execute {@link Event} - when the whole combination got typed (the matching key's default action is prevented).
+     */
     let PacemShortcutElement = class PacemShortcutElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
             this._accumulator = [];
             this._shortcutHandler = (evt) => {
+                // a disabled shortcut leaves the keys alone (no execute, and no prevented default either)
+                if (this.disabled) {
+                    this._accumulator.splice(0);
+                    return;
+                }
                 const result = (matchesKeyCombination(evt, this.combination, this._accumulator));
                 switch (result) {
                     case true:
@@ -8411,7 +8545,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. */
+    /**
+     * Wraps a {@link Worker}, sending/receiving messages to/from a web worker script.
+     * @fires receive {@link CustomEvent} - when the worker posts a message back: `detail` is the message (also in `result`).
+     * @fires error {@link CustomEvent} - when the worker script fails: `detail` is the error, when the browser can pass it over.
+     */
     let PacemWebWorkerProxyElement = class PacemWebWorkerProxyElement extends PacemEventTarget {
         constructor() {
             super(...arguments);
@@ -8480,6 +8618,10 @@
                 worker.removeEventListener('message', this._messageHandler, false);
                 worker.terminate();
             }
+            // (a terminated worker takes no more messages)
+            if (worker === this._worker) {
+                this._worker = null;
+            }
         }
     };
     __decorate$9([
@@ -8916,6 +9058,13 @@
     /**
      * 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}.
+     * @fires draginit {@link DragDropEvent} - on press, before anything moves: cancelable (`preventDefault()` refuses the drag).
+     * @fires dragstart {@link DragDropEvent} - when the drag actually starts (the press lasted `lockTimeout`).
+     * @fires drag {@link DragDropEvent} - on every move: cancelable.
+     * @fires dragover {@link DragDropEvent} - when hovering one of the `dropTargets`: cancelable (`preventDefault()` refuses that target).
+     * @fires dragout {@link DragDropEvent} - when leaving a drop target.
+     * @fires drop {@link DragDropEvent} - on release over a drop target: `detail.target` is the target, `detail.element` the dragged element.
+     * @fires dragend {@link DragDropEvent} - when it's all over (dropped or not).
      */
     let PacemDragDropElement = class PacemDragDropElement extends PacemBehavior {
         constructor() {
@@ -9041,7 +9190,42 @@
         else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
-    //namespace Pacem.Components {
+    /** Clamps `value` into `[min, max]`. */
+    function clamp(value, min, max) {
+        if (value < min) {
+            return min;
+        }
+        return Math.min(value, max);
+    }
+    /**
+     * Clamps a desired rect to the size constraints, keeping the edges opposite to the dragged handle in place
+     * (a top/left handle moves the rect's origin, a bottom/right one doesn't).
+     * @param rect The desired rect.
+     * @param handle The dragged handle (`top`, `bottomleft`…).
+     * @param constraints Minimum and maximum width and height.
+     * @returns The clamped rect.
+     */
+    function clampToConstraints(rect, handle, constraints) {
+        const width = clamp(rect.width, constraints.minWidth, constraints.maxWidth);
+        const height = clamp(rect.height, constraints.minHeight, constraints.maxHeight);
+        const x = handle.endsWith('left') ? rect.x + rect.width - width : rect.x;
+        const y = handle.startsWith('top') ? rect.y + rect.height - height : rect.y;
+        return { x, y, width, height };
+    }
+    /**
+     * What an element's `width`/`height` leave out of its border box: nothing for `border-box`, padding and border for
+     * `content-box` (so that a border-box size can be written as `width`/`height` whatever the box sizing).
+     * @param computed The element's computed style.
+     */
+    function boxChrome(computed) {
+        if (computed.boxSizing === 'border-box') {
+            return { width: 0, height: 0 };
+        }
+        const px = (value) => parseFloat(value) || 0;
+        const width = px(computed.paddingLeft) + px(computed.paddingRight) + px(computed.borderLeftWidth) + px(computed.borderRightWidth);
+        const height = px(computed.paddingTop) + px(computed.paddingBottom) + px(computed.borderTopWidth) + px(computed.borderBottomWidth);
+        return { width, height };
+    }
     class RescaleElementDelegate {
         constructor(_element, _type, _rescaler, _logFn) {
             this._element = _element;
@@ -9109,9 +9293,13 @@
                 this._logFn(LogLevel.Log, `handle: ${handle}, origin: ${JSON.stringify(origin)}, currentPosition: ${JSON.stringify(currentPosition)}`, `Rescaling`);
                 this._logFn(LogLevel.Log, `delta: ${JSON.stringify(delta)}, position: ${JSON.stringify(position)}`, `Rescaling`);
                 this._logFn(LogLevel.Log, `from: ${JSON.stringify(this._rect)}, to: ${JSON.stringify(desiredRect)}`, `Rescaling`);
+                // free rescaling: a move beyond the constraints is clamped to them (a fast drag still reaches the limit)
+                if (!keepProportions) {
+                    desiredRect = clampToConstraints(desiredRect, handle, { minWidth, maxWidth, minHeight, maxHeight });
+                }
                 // check constraints
                 let horizontally = desiredRect.width >= minWidth && desiredRect.width <= maxWidth, vertically = desiredRect.height >= minHeight && desiredRect.height <= maxHeight;
-                // if proportions are constrained and one fails, then both fail
+                // if proportions are constrained and one fails, then both fail (clamping one side would break the ratio)
                 if (keepProportions && (!horizontally || !vertically)) {
                     horizontally = vertically = false;
                 }
@@ -9137,8 +9325,10 @@
                         // render resize
                         const m = this._originalTransform;
                         el.style.transform = `matrix(${m.a},${m.b},${m.c},${m.d},${(m.e + desiredRect.x - this._rect.x)},${(m.f + desiredRect.y - this._rect.y)})`;
-                        el.style.width = desiredRect.width + 'px';
-                        el.style.height = desiredRect.height + 'px';
+                        // (the rect is a border box: a content-box element gets it minus its padding and border)
+                        const chrome = this._chrome;
+                        el.style.width = Math.max(desiredRect.width - chrome.width, 0) + 'px';
+                        el.style.height = Math.max(desiredRect.height - chrome.height, 0) + 'px';
                     }
                     // store targetRect
                     this._targetRect = desiredRect;
@@ -9171,7 +9361,9 @@
                 this._targetRect =
                     Utils.offsetRect(_element);
             //
-            this._originalTransform = Utils.deserializeTransform(getComputedStyle(_element));
+            const computed = getComputedStyle(_element);
+            this._originalTransform = Utils.deserializeTransform(computed);
+            this._chrome = boxChrome(computed);
             // body
             Utils.addClass(document.body, PCSS + '-rescaling rescale-' + _type);
         }
@@ -9186,6 +9378,11 @@
     /**
      * Pacem Rescale element adapter: implements {@link Rescaler} on top of {@link PacemBehavior}, decorating
      * registered elements with draggable resize handles (see {@link RescaleHandle}).
+     * A move beyond the size constraints (`minWidth`, `maxWidth`, `minHeight`, `maxHeight`) is clamped to them; with
+     * `keepProportions`, such a move is ignored instead (clamping one side would break the ratio).
+     * @fires rescalestart {@link RescaleEvent} - when a handle gets grabbed: `detail.handle` tells which.
+     * @fires rescale {@link RescaleEvent} - on every move: `detail.targetRect` is the size about to be applied; cancelable (`preventDefault()` applies nothing, e.g. to apply it your way).
+     * @fires rescaleend {@link RescaleEvent} - when the handle gets released: `detail.targetRect` is the final size.
      */
     let PacemRescaleElement = class PacemRescaleElement extends PacemBehavior {
         constructor() {
@@ -9407,6 +9604,9 @@
     /**
      * 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.
+     * @fires rotatestart {@link RotateEvent} - on press: cancelable (`preventDefault()` refuses the gesture).
+     * @fires rotate {@link RotateEvent} - whenever the (stepped) angle changes: `detail.rotation`, in radians; cancelable (nothing gets rendered).
+     * @fires rotateend {@link RotateEvent} - on release: `detail.rotation` is the final angle.
      */
     let PacemRotateElement = class PacemRotateElement extends PacemBehavior {
         constructor() {
@@ -9512,9 +9712,10 @@
                 swiper.dispatchEvent(swipeEvt);
                 if (!swipeEvt.defaultPrevented) {
                     let { delta } = this._delta(this._init, state);
-                    if (!swiper.options.bouncy) {
+                    // (the merged options: the swiper's own `options` may well be unset, defaults apply)
+                    if (!this.#options.bouncy) {
                         // clamp delta just in case
-                        const snaps = swiper.snaps.slice().sort();
+                        const snaps = swiper.snaps.slice().sort((a, b) => a - b);
                         const snapFirst = snaps[0], snapLast = snaps[snaps.length - 1];
                         const dir = this._swiper.direction;
                         const { x, y } = delta;
@@ -9534,25 +9735,26 @@
                     console.log('How come?!');
                 }
                 else {
-                    const args = this._buildSwipeArgsFromState();
-                    const swipeEvt = new SwipeEvent(SwipeEventType.Swipe, args, { cancelable: true, bubbles: false });
                     const swiper = this._swiper;
+                    // where the element is going to rest: the snap nearest to where its momentum carries it (known before
+                    // dispatching, so that every event of the release tells it: `detail.snap`, 0 meaning back home)
+                    const estimate = this._buildSwipeArgsFromState();
+                    // (a numeric copy: the swiper's own array stays as it is)
+                    const snaps = (swiper.snaps ?? [0.0]).slice().sort((a, b) => a - b);
+                    const target = this.#options.bouncy ? estimate.predictedDelta : estimate.predictedDelta.clamp(snaps[0], snaps[snaps.length - 1]);
+                    const snap = snaps.reduce((acc, v) => {
+                        const distance = Math.abs(v - target);
+                        const current = Math.abs(acc - target);
+                        return distance < current ? v : acc;
+                    }, 0);
+                    const args = this._buildSwipeArgsFromState(this.#state, snap);
+                    const swipeEvt = new SwipeEvent(SwipeEventType.Swipe, args, { cancelable: true, bubbles: false });
                     swiper.dispatchEvent(swipeEvt);
                     if (!swipeEvt.defaultPrevented) {
                         const swipe1Evt = new SwipeEvent(("swipe" + args.direction), args, { cancelable: true, bubbles: false });
                         swiper.dispatchEvent(swipe1Evt);
                         if (!swipe1Evt.defaultPrevented) {
-                            // if the predicted distance is greater than the original position + half the distance to the nearest snap,
-                            const snaps = swiper.snaps ?? [0.0];
-                            snaps.sort();
-                            const target = swiper.options.bouncy ? args.predictedDelta : args.predictedDelta.clamp(snaps[0], snaps[snaps.length - 1]);
-                            // then animate toward that target,
-                            // otherwise bounce back
-                            const snap = snaps.reduce((acc, v) => {
-                                const distance = Math.abs(v - target);
-                                const current = Math.abs(acc - target);
-                                return distance < current ? v : acc;
-                            }, 0);
+                            // animate toward the target, then settle on the snap (or bounce back home)
                             const vertical = swiper.direction === 'vertical';
                             const duration = args.predictedDuration;
                             const delta0 = vertical ? { x: 0, y: target } : { x: target, y: 0 };
@@ -9566,7 +9768,11 @@
                             };
                             if (snap.isCloseTo(0)) {
                                 this._animateOffsetBy(delta0, duration).then(() => {
-                                    this._animateOffsetBy({ x: 0, y: 0 }, .3, 'cubic-bezier(.37,-0.01,.34,1.43)').then(() => swipeAnimationEnd());
+                                    this._animateOffsetBy({ x: 0, y: 0 }, .3, 'cubic-bezier(.37,-0.01,.34,1.43)').then(() => {
+                                        // back home exactly: the committed (overshooting) animation leaves float noise behind
+                                        this._element.style.transform = this.#originalInlineTransform;
+                                        swipeAnimationEnd();
+                                    });
                                 });
                             }
                             else {
@@ -9596,6 +9802,7 @@
             const el = _element;
             this.#options = Utils.extend({}, DEFAULT_OPTIONS, _swiper.options ?? {});
             this.#originalTransform = Utils.deserializeTransform(getComputedStyle(el));
+            this.#originalInlineTransform = el.style.transform;
             window.addEventListener('pointermove', this._moveHandler, false);
             window.addEventListener('pointerup', this._endHandler, false);
             window.addEventListener('pointercancel', this._endHandler, false);
@@ -9633,7 +9840,12 @@
             };
             return state;
         }
-        _buildSwipeArgsFromState(state = this.#state) {
+        /**
+         * Builds the event args of the current state.
+         * @param state The gesture state.
+         * @param snap The snap the element is going to rest at, once known (on release).
+         */
+        _buildSwipeArgsFromState(state = this.#state, snap) {
             const options = this.#options;
             const speed = this.speed;
             const dir = this._swiper.direction;
@@ -9648,7 +9860,7 @@
             // console.log(`v speed: ${verticalspeed}`);
             const args = SwipeEventArgsClass.fromArgs({
                 position: state.position, element: this._element, t0: this._init, timestamp: state.timestamp, inertia: options.inertia, fling: options.fling,
-                horizontalspeed, verticalspeed, vertical
+                horizontalspeed, verticalspeed, vertical, snap
             });
             //console.log(args);
             return args;
@@ -9677,6 +9889,8 @@
         #options;
         #samples;
         #originalTransform;
+        /** The element's inline `transform` before the gesture, restored as is on a bounce-back home. */
+        #originalInlineTransform;
         #state;
         dispose() {
             const el = this._element;
@@ -9688,6 +9902,11 @@
     /**
      * 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.
+     * @fires pan {@link SwipeEvent} - while the element follows the pointer: cancelable.
+     * @fires swipe {@link SwipeEvent} - on release, once a swipe is detected (dragged past a snap, or flung): cancelable (stops the chain).
+     * @fires swipe{direction} {@link SwipeEvent} - right after `swipe`, named after the direction (`swipeleft`, `swiperight`, `swipeup`, `swipedown`): cancelable.
+     * @fires swipeanimationend {@link SwipeEvent} - when the element reached its snap: cancelable (`preventDefault()` keeps it there instead of returning).
+     * @fires swipe{direction}animationend {@link SwipeEvent} - right after `swipeanimationend`, named after the direction.
      */
     let PacemSwipeElement = class PacemSwipeElement extends PacemBehavior {
         constructor() {