@pacem/pacem-2d 1.0.0-bessel → 1.0.0-binet

package/dist/browser/pacem-2d.js

@@ -1,31 +1,44 @@
 /*!
- * @pacem/pacem-2d v1.0.0-bessel (https://js.pacem.it)
+ * @pacem/pacem-2d v1.0.0-binet (https://js.pacem.it)
  * Pacem (https://pacem.it)
  * Licensed under Apache-2.0
  */
 (function (pacemFoundation, pacemCore) {
     'use strict';
 
+    /** Middle segment shared by every `<pacem-2d-*>` custom element tag name. */
     const TAG_MIDDLE_NAME = "2d";
 
+    /** Type guard telling whether `object` implements `Drawable`. */
     function isDrawable(object) {
         return !pacemCore.Utils.isNull(object) && 'stage' in object;
     }
+    /** Type guard telling whether `object` implements `UiObject`. */
     function isUiObject(object) {
         return /*'transformMatrix' in object &&*/ isDrawable(object);
     }
     function isGradient(object) {
         return 'stops' in object && pacemCore.Utils.isArray(object.stops);
     }
+    /** Type guard telling whether `object` is a `LinearGradient`. */
     function isLinearGradient(object) {
         return isGradient(object) && 'start' in object && pacemFoundation.Point.isPoint(object.start)
             && 'end' in object && pacemFoundation.Point.isPoint(object.end);
     }
+    /** Type guard telling whether `object` is a `RadialGradient`. */
     function isRadialGradient(object) {
         return isGradient(object) && 'center' in object && pacemFoundation.Point.isPoint(object.center)
             && 'radius' in object && typeof object.radius === 'number';
     }
+    /** Static helpers to combine `PresentationState` instances (e.g. a shape's own state with its inherited parent state). */
     class PresentationState {
+        /**
+         * Combines two presentation states (typically an item's own state and the one inherited from its
+         * ancestors), giving precedence to `lhs` whenever both define a value.
+         * @param lhs Own/most specific presentation state.
+         * @param rhs Inherited/fallback presentation state.
+         * @param precomputedMatrix If provided, used as-is instead of multiplying `lhs`'s and `rhs`'s transform matrices.
+         */
         static combine(lhs, rhs, precomputedMatrix = null) {
             return {
                 opacity: (lhs.opacity ?? 1) * (rhs.opacity ?? 1),
@@ -39,6 +52,7 @@
             };
         }
     }
+    /** Type guard telling whether `object` implements `PresentationObject`. */
     function isPresentationObject(object) {
         return isUiObject(object)
             && ('fill' in object
@@ -50,18 +64,26 @@
                 || 'opacity' in object
                 || 'lineCap' in object);
     }
+    /** Type guard telling whether `object` implements `Shape`. */
     function isShape(object) {
         return isUiObject(object) && 'pathData' in object;
     }
+    /** Type guard telling whether `object` implements `Group` and has at least one child drawable. */
     function isGroup(object) {
         return isUiObject(object) && 'childDrawables' in object && !pacemCore.Utils.isNullOrEmpty(object['childDrawables']);
     }
+    /** Type guard telling whether `object` implements `Text`. */
     function isText(object) {
         return isUiObject(object) && 'text' in object && typeof object['text'] === 'string';
     }
+    /** Type guard telling whether `object` implements `Image`. */
     function isImage(object) {
         return isUiObject(object) && 'src' in object && typeof object['src'] === 'string';
     }
+    /**
+     * Base class for the custom UI events dispatched by the 2D stage/adapters, carrying the screen transform
+     * matrix in effect at dispatch time so consumers can project screen coordinates into stage coordinates.
+     */
     class UI2DEvent extends pacemCore.CustomUIEvent {
         constructor(type, eventInit, originalEvent, transformMatrix) {
             super(type, eventInit, originalEvent);
@@ -72,22 +94,28 @@
         get transformMatrix() {
             return this.#transformMatrix;
         }
+        /** Projects a point (defaults to the event's screen coordinates) through the event's transform matrix. */
         project(pt = { x: this.screenX, y: this.screenY }) {
             return pacemFoundation.Matrix2D.multiply(pt, this.#transformMatrix);
         }
     }
+    /** Static helper to build an empty `ShapeGeometry`. */
     class Shape {
+        /** Returns an empty `ShapeGeometry` (no path, no vertices, zero-sized bounding rect). */
         static empty() {
             return { pathData: '', vertices: [], boundingRect: { x: 0, y: 0, width: 0, height: 0 } };
         }
     }
+    /** Event dispatched throughout a `Drawable`'s drag lifecycle, carrying `DragEventArgs`. */
     class DragEvent extends UI2DEvent {
     }
+    /** Event dispatched for pointer interactions (over/out/down/up/click) targeting a `Drawable`. */
     class DrawableEvent extends UI2DEvent {
         constructor(type, args, originalEvent, m) {
             super(type, { detail: args, bubbles: true, cancelable: true }, originalEvent, m);
         }
     }
+    /** Event dispatched for pointer interactions (move/down/up/click) targeting a `Stage` at large (i.e. no specific hit `Drawable`). */
     class StageEvent extends UI2DEvent {
         constructor(type, args, originalEvent, m = args.transformMatrix) {
             super(type, { detail: args, bubbles: true, cancelable: true }, originalEvent, m);
@@ -148,10 +176,20 @@
         zoomModifiers: [pacemCore.EventKeyModifier.AltKey],
         clickModifiers: []
     };
+    /**
+     * Returns the effective `StageOptions` for the given stage, filling in any option left unset with the
+     * library defaults.
+     * @param stage The stage to resolve options for.
+     */
     function getStageOptions(stage) {
         const options = stage instanceof Pacem2DElement ? stage.options : {};
         return pacemCore.Utils.extend({}, DEFAULT_STAGE_OPTIONS, options);
     }
+    /**
+     * The `<pacem-2d>` element: root stage/scene container for the drawable elements (shapes, text, images,
+     * groups...). Delegates actual rendering to the assigned `adapter` (SVG or Canvas) and handles the
+     * viewbox/aspect-ratio mapping plus built-in pan and zoom interactions.
+     */
     let Pacem2DElement = class Pacem2DElement extends pacemCore.Components.PacemItemsContainerElement {
         constructor() {
             super(...arguments);
@@ -216,9 +254,11 @@
                 this.#panningStart = null;
             };
         }
+        /** @readonly Gets the DOM element hosting the stage content. */
         get stage() {
             return this._stage;
         }
+        /** Processes the stage content and returns a snapshot image (delegates to the current `adapter`). */
         snapshot(bgColor, type, quality) {
             const adapter = this.adapter;
             if (pacemCore.Utils.isNull(adapter)) {
@@ -228,6 +268,7 @@
         }
         #originalViewBox;
         #transformMatrix;
+        /** @readonly Gets the matrix that projects stage coords into screen coords. */
         get transformMatrix() {
             return this.#transformMatrix;
         }
@@ -479,6 +520,11 @@
         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;
     };
+    /**
+     * Root of the `<pacem-2d-*>` drawable elements hierarchy: wires a custom element up to its containing
+     * `Pacem2DElement` stage and, in case of nesting, its parent drawable. By default children are not allowed
+     * (only `PacemGroupElement` overrides `validate` to accept them).
+     */
     class DrawableElement extends pacemCore.Components.PacemCrossItemsContainerElement {
         validate(_) {
             // by default no children allowed (Group will except)
@@ -488,9 +534,11 @@
             // override
             return this.parent || this.stage;
         }
+        /** @readonly Gets the `Pacem2DElement` stage this drawable belongs to. */
         get stage() {
             return this['_scene'] = this['_scene'] || pacemCore.CustomElementUtils.findAncestorOfType(this, Pacem2DElement);
         }
+        /** @readonly Gets the closest ancestor `DrawableElement` (e.g. a containing group), if any. */
         get parent() {
             return this['_drawableParent'] = this['_drawableParent'] || pacemCore.CustomElementUtils.findAncestor(this, i => i instanceof DrawableElement);
         }
@@ -525,6 +573,10 @@
     };
     //namespace Pacem.Components.Drawing {
     const DEG2RAD = Math.PI / 180.0;
+    /**
+     * Base class for every drawable that participates in the 2D transform pipeline (rotation, scale,
+     * translation) and exposes an `opacity`. Computes and caches the corresponding `transformMatrix`.
+     */
     class UiElement extends DrawableElement {
         #transformMatrix = pacemFoundation.Matrix2D.identity;
         viewActivatedCallback() {
@@ -576,6 +628,10 @@
     __decorate$b([
         pacemCore.Watch({ emit: false, converter: pacemCore.PropertyConverters.Number })
     ], UiElement.prototype, "opacity", void 0);
+    /**
+     * Base class for drawables that carry stroke/fill presentation state (color, line width, dash pattern,
+     * line join/cap), on top of the transform/opacity inherited from `UiElement`.
+     */
     class PresentationElement extends UiElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -618,6 +674,11 @@
     __decorate$b([
         pacemCore.Watch({ emit: false, converter: pacemCore.PropertyConverters.String })
     ], PresentationElement.prototype, "lineCap", void 0);
+    /**
+     * Base class for drawables whose visual is an SVG path (`pathData`) computed out of their own geometry
+     * properties (e.g. center/radius, points, corners). Subclasses implement `getShapeGeometry` and this
+     * class takes care of recomputing `data`/`vertices`/`boundingRect` and requesting a redraw.
+     */
     class ShapeElement extends PresentationElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -633,20 +694,24 @@
             super.viewActivatedCallback();
             this.recomputeShape();
         }
+        /** Recomputes `data`, `vertices` and `boundingRect` from `getShapeGeometry()`. */
         recomputeShape() {
             const { pathData, vertices, boundingRect } = this.getShapeGeometry();
             this.#vertices = vertices;
             this.#boundingRect = boundingRect;
             this.data = pathData;
         }
+        /** @readonly Gets the SVG path data backing the shape. */
         get pathData() {
             return this.data;
         }
         #boundingRect;
+        /** @readonly Gets the bounding rectangle of the shape. */
         get boundingRect() {
             return this.#boundingRect;
         }
         #vertices;
+        /** @readonly Gets the vertices making up the shape. */
         get vertices() {
             return this.#vertices;
         }
@@ -662,11 +727,13 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Drawing {
+    /** `<pacem-2d-group>`: a container that groups child drawables, applying its own transform/presentation state to all of them. */
     let PacemGroupElement = class PacemGroupElement extends PresentationElement {
         validate(item) {
             return item instanceof DrawableElement && item.parent === this;
         }
         #children = [];
+        /** @readonly Gets the child drawables currently in the group. */
         get childDrawables() {
             return this.#children;
         }
@@ -749,6 +816,7 @@
         const threesixty = (start - end).isCloseTo(0);
         return threesixty ? full(c, rx, ry) : sect(c, rx, ry, start, end);
     }
+    /** `<pacem-2d-ellipse>`: renders a full ellipse, or a pie-slice sector when `start`/`end` are set. */
     let PacemEllipseElement = PacemEllipseElement_1 = class PacemEllipseElement extends ShapeElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -764,6 +832,7 @@
                 }
             }
         }
+        /** Computes the SVG path data of the ellipse (or sector) out of its own `center`/`rx`/`ry`/`start`/`end`. */
         getPathData() {
             const a = this.rx, b = this.ry, c = this.center, s = this.start ?? 0, e = this.end ?? 0;
             if (!pacemCore.Utils.isNull(c) && !pacemCore.Utils.isNull(a) && !pacemCore.Utils.isNull(b)) {
@@ -776,6 +845,14 @@
             const a = this.rx ?? 0, b = this.ry ?? 0;
             return getShapeGeometry(center, a, b, this.start, this.end);
         }
+        /**
+         * Computes the SVG path data of an ellipse, or of a pie-slice sector when `start`/`end` don't describe a full turn.
+         * @param c Center point.
+         * @param rx Horizontal radius.
+         * @param ry Vertical radius.
+         * @param start Sector start angle, in degrees.
+         * @param end Sector end angle, in degrees.
+         */
         static getPathData(c = { x: NaN, y: NaN }, rx = NaN, ry = NaN, start, end) {
             const { pathData } = getShapeGeometry(c, rx, ry, start, end);
             return pathData;
@@ -799,6 +876,7 @@
     PacemEllipseElement = PacemEllipseElement_1 = __decorate$9([
         pacemCore.CustomElement({ tagName: pacemCore.P + '-' + TAG_MIDDLE_NAME + '-ellipse' })
     ], PacemEllipseElement);
+    /** `<pacem-2d-circle>`: renders a full circle, or a pie-slice sector when `start`/`end` are set. */
     let PacemCircleElement = PacemCircleElement_1 = class PacemCircleElement extends ShapeElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -813,6 +891,7 @@
                 }
             }
         }
+        /** Computes the SVG path data of the circle (or sector) out of its own `center`/`radius`/`start`/`end`. */
         getPathData() {
             const r = this.radius, c = this.center;
             if (!pacemCore.Utils.isNull(c) && !pacemCore.Utils.isNull(r)) {
@@ -825,6 +904,13 @@
             const r = this.radius ?? 0;
             return getShapeGeometry(center, r, r, this.start, this.end);
         }
+        /**
+         * Computes the SVG path data of a circle, or of a pie-slice sector when `start`/`end` don't describe a full turn.
+         * @param c Center point.
+         * @param r Radius.
+         * @param start Sector start angle, in degrees.
+         * @param end Sector end angle, in degrees.
+         */
         static getPathData(c = { x: NaN, y: NaN }, r = NaN, start, end) {
             return PacemEllipseElement.getPathData(c, r, r, start, end);
         }
@@ -901,11 +987,13 @@
         const blX = stringifyCornerRadiusComponent(bottomLeft.rx), blY = stringifyCornerRadiusComponent(bottomLeft.ry);
         return `${tlX},${tlY} ${trX},${trY} ${brX},${brY} ${blX},${blY}`;
     }
+    /** How a `PacemRectElement` corner is rendered: smoothly `Rounded` or straight-line `Cut` (chamfered). */
     var CornerType;
     (function (CornerType) {
         CornerType["Rounded"] = "rounded";
         CornerType["Cut"] = "cut";
     })(CornerType || (CornerType = {}));
+    /** `<pacem-2d-rect>`: renders a rectangle, optionally with independently rounded or cut corners. */
     let PacemRectElement = PacemRectElement_1 = class PacemRectElement extends ShapeElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -913,6 +1001,7 @@
                 this.recomputeShape();
             }
         }
+        /** Computes the SVG path data of the rectangle out of its own `x`/`y`/`w`/`h`/`r`/`cornerType`. */
         getPathData() {
             const x = this.x, y = this.y, w = this.w, h = this.h;
             let r = this.r ?? { rx: { value: 0 }, ry: { value: 0 }, type: CornerType.Rounded };
@@ -1024,6 +1113,7 @@
     };
     var PacemLineElement_1;
     //namespace Pacem.Components.Drawing {
+    /** `<pacem-2d-line>`: renders a straight segment between two points. */
     let PacemLineElement = PacemLineElement_1 = class PacemLineElement extends ShapeElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -1045,6 +1135,7 @@
             const boundingRect = { x: Math.min(x0, x1), y: Math.min(y0, y1), width: Math.abs(x0 - x1), height: Math.abs(y0 - y1) };
             return { pathData: this.getPathData(), vertices: [from, to], boundingRect };
         }
+        /** Computes the SVG path data of the line out of its own `from`/`to` points. */
         getPathData() {
             const from = this.from, to = this.to;
             if (!pacemCore.Utils.isNull(from) && !pacemCore.Utils.isNull(to)) {
@@ -1052,6 +1143,7 @@
             }
             return null;
         }
+        /** Computes the SVG path data of a straight segment between `from` and `to`. */
         static getPathData(from = { x: NaN, y: NaN }, to = { x: NaN, y: NaN }) {
             const x0 = from.x, y0 = from.y, x1 = to.x, y1 = to.y;
             return `M ${x0} ${y0} L ${x1} ${y1}`;
@@ -1074,9 +1166,11 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Drawing {
+    /** `<pacem-2d-path>`: renders an arbitrary SVG path, provided verbatim through the `d` property. */
     let PacemPathElement = class PacemPathElement extends ShapeElement {
         constructor() {
             super(...arguments);
+            /** Returns the raw path data, i.e. `d`. */
             this.getPathData = () => this.d;
         }
         propertyChangedCallback(name, old, val, first) {
@@ -1104,6 +1198,7 @@
     };
     var PacemPolygonElement_1;
     //namespace Pacem.Components.Drawing {
+    /** `<pacem-2d-polygon>`: renders a regular polygon (or, with `starIndent` set, a star) centered on `center`. */
     let PacemPolygonElement = PacemPolygonElement_1 = class PacemPolygonElement extends ShapeElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -1117,6 +1212,7 @@
                 }
             }
         }
+        /** Computes the SVG path data of the polygon out of its own `center`, `radius`, `sides` and `starIndent`. */
         getPathData() {
             const sides = this.sides, radius = this.radius, center = this.center;
             if (!pacemCore.Utils.isNull(sides) && !pacemCore.Utils.isNull(radius)) {
@@ -1131,6 +1227,13 @@
             }
             return PacemPolygonElement_1.getShapeGeometry(c, r, sides, si);
         }
+        /**
+         * Computes the geometry (path data, vertices, bounding rect) of a regular polygon or star.
+         * @param center Center point.
+         * @param radius Circumradius.
+         * @param sides Number of sides (or points, for a star).
+         * @param starIndent Star indentation factor (0 = regular polygon).
+         */
         static getShapeGeometry(center, radius, sides, starIndent = .0) {
             const p0 = { x: center.x, y: center.y - radius };
             let retval = `M ${p0.x} ${(p0.y)}`;
@@ -1161,6 +1264,7 @@
                 pathData: retval + ' Z', vertices, boundingRect: { x: p0.x - radius, y: p0.y, width, height: width }
             };
         }
+        /** Computes the SVG path data of a regular polygon or star. See `getShapeGeometry` for the parameters. */
         static getPathData(center, radius, sides, starIndent = .0) {
             const { pathData } = PacemPolygonElement_1.getShapeGeometry(center, radius, sides, starIndent);
             return pathData;
@@ -1190,6 +1294,7 @@
     };
     var PacemPolylineElement_1;
     //namespace Pacem.Components.Drawing {
+    /** Converts the `points` attribute either from a flat `x1,y1,x2,y2,...` numeric list or from JSON. */
     const PointArrayOrJsonConverter = {
         convert: (attr) => {
             const arr = pacemFoundation.parseAsNumericalArray(attr);
@@ -1204,6 +1309,7 @@
         },
         convertBack: (prop) => JSON.stringify(prop)
     };
+    /** `<pacem-2d-polyline>`: renders a series of connected segments through `points`, optionally `closed` into a polygon. */
     let PacemPolylineElement = PacemPolylineElement_1 = class PacemPolylineElement extends ShapeElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -1216,6 +1322,11 @@
                 }
             }
         }
+        /**
+         * Computes the geometry (path data, vertices, bounding rect) of a polyline.
+         * @param points Vertices, in order.
+         * @param closed Whether the polyline is closed back onto its first point.
+         */
         static getShapeGeometry(points, closed) {
             if (pacemCore.Utils.isNullOrEmpty(points)) {
                 return Shape.empty();
@@ -1239,10 +1350,12 @@
         getShapeGeometry() {
             return PacemPolylineElement_1.getShapeGeometry(this.points, this.closed);
         }
+        /** Computes the SVG path data of the polyline out of its own `points`/`closed`. */
         getPathData() {
             const { pathData } = this.getShapeGeometry();
             return pathData;
         }
+        /** Computes the SVG path data of a polyline. See `getShapeGeometry` for the parameters. */
         static getPathData(points, closed) {
             const { pathData } = PacemPolylineElement_1.getShapeGeometry(points, closed);
             return pathData;
@@ -1265,6 +1378,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Drawing {
+    /** `<pacem-2d-image>`: renders a raster image at a given position and size within the stage. */
     let PacemImageElement = class PacemImageElement extends UiElement {
         propertyChangedCallback(name, old, val, first) {
             super.propertyChangedCallback(name, old, val, first);
@@ -1307,6 +1421,7 @@
         return c > 3 && r && Object.defineProperty(target, key, r), r;
     };
     //namespace Pacem.Components.Drawing {
+    /** `<pacem-2d-text>`: renders a text label anchored at a given point. */
     let PacemTextElement = class PacemTextElement extends UiElement {
         propertyChangedCallback(name, old, val, first) {
             if (!first) {
@@ -1355,12 +1470,20 @@
     ], PacemTextElement);
 
     //namespace Pacem.Components.Drawing {
+    /** Shared static helpers used by the 2D rendering adapters (SVG/Canvas) to dispatch UI events and validate viewboxes. */
     class AdapterUtils {
+        /**
+         * Dispatches a `StageEvent` (prefixed with `'stage'`) on the given stage, when it is an `EventTarget`.
+         * @param stage The target stage.
+         * @param type Short event type name.
+         * @param evt The original event.
+         */
         static stageDispatch(stage, type, evt) {
             if (stage instanceof EventTarget) {
                 stage.dispatchEvent(new StageEvent('stage' + type, stage, evt, stage.transformMatrix));
             }
         }
+        /** Type guard telling whether `viewbox` is a well-formed, finite `Rect` usable as a stage viewbox. */
         static isValidViewbox(viewbox) {
             return !pacemCore.Utils.isNullOrEmpty(viewbox) && pacemFoundation.Rect.isRect(viewbox) && Number.isFinite(viewbox.x) // isFinite includes NaN check
                 && Number.isFinite(viewbox.y) && Number.isFinite(viewbox.width) && Number.isFinite(viewbox.height);
@@ -1403,15 +1526,29 @@
     }
 
     const JPEG_QUALITY = .9;
+    /**
+     * Base class for the rendering adapters (SVG, Canvas) assignable to a `Pacem2DElement` stage. Concrete
+     * adapters are responsible for initializing/disposing the underlying DOM surface, sizing it, drawing the
+     * scene graph, hit-testing and producing snapshot images.
+     */
     class Pacem2DAdapterElement extends pacemCore.PacemEventTarget {
         constructor() {
             super(...arguments);
+            /** Fallback stroke/fill/lineWidth values used when a shape doesn't provide its own. */
             this.DefaultShapeValues = {
                 stroke: "#000",
                 lineWidth: 1,
                 fill: "#fff"
             };
         }
+        /**
+         * Rasterizes the given DOM element into an image `Blob`, defaulting to JPEG when `bgColor` is provided
+         * (to flatten transparency against it) and to PNG otherwise.
+         * @param element Element to snapshot.
+         * @param bgColor Background color to flatten transparency against; if set, defaults `type` to `'image/jpeg'`.
+         * @param type Explicit image MIME type, overrides the `bgColor`-based default.
+         * @param quality Compression quality, applicable to lossy formats (defaults to `.9` for JPEG).
+         */
         snapshotElement(element, bgColor, type, quality) {
             const jpeg = !pacemCore.Utils.isNullOrEmpty(bgColor), mime = type ?? (jpeg ? 'image/jpeg' : null), compression = quality ?? (jpeg ? JPEG_QUALITY : null);
             return pacemCore.Utils.snapshotElement(element, bgColor, mime, compression);
@@ -1435,7 +1572,12 @@
     function fallback$1(v, f) {
         return pacemCore.Utils.isNull(v) ? f : v;
     }
-    /** Implementation postponed. Focus on SVG adapter. */
+    /**
+     * `<pacem-2d-canvas-adapter>`: renders a `Pacem2DElement` stage onto an `HTMLCanvasElement`, redrawing the
+     * whole scene graph on every frame and performing manual (path-based) pointer hit-testing.
+     *
+     * @deprecated Implementation postponed. Focus on SVG adapter.
+     */
     let PacemCanvasAdapterElement = class PacemCanvasAdapterElement extends Pacem2DAdapterElement {
         constructor() {
             super(...arguments);
@@ -2063,6 +2205,11 @@
             return parent.replaceChild(newChild, parent.children.item(targetIndex));
         }
     }
+    /**
+     * `<pacem-2d-svg-adapter>`: renders a `Pacem2DElement` stage as an inline SVG document, keeping one SVG
+     * element per drawable in sync (path/text/image/group), along with markers and gradients, and drives
+     * pointer hit-testing and drag & drop through the SVG DOM.
+     */
     let PacemSvgAdapterElement = class PacemSvgAdapterElement extends Pacem2DAdapterElement {
         constructor() {
             super(...arguments);