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

package/typings/index.d.ts

@@ -8,8 +8,16 @@ import { Rect } from '@pacem/pacem-foundation';
 import { Size } from '@pacem/pacem-foundation';
 import { UI } from '@pacem/pacem-core';
 
+/** Shared static helpers used by the 2D rendering adapters (SVG/Canvas) to dispatch UI events and validate viewboxes. */
 declare 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: Stage, type: 'down' | 'up' | 'click' | 'over' | 'out' | 'move', evt: MouseEvent | TouchEvent): void;
+    /** Type guard telling whether `viewbox` is a well-formed, finite `Rect` usable as a stage viewbox. */
     static isValidViewbox(viewbox: any): viewbox is Rect;
     /**
      * Dispatches a UI event related to a `Drawable` and returns a boolean that tells if the event was prevented (true) or not (false).
@@ -33,30 +41,36 @@ export declare namespace Components {
     }
 }
 
+/** Radius (x/y) and treatment (rounded or cut) applied to a single corner of a `PacemRectElement`. */
 declare type CornerRadius = {
     rx: CornerRadiusComponent;
     ry: CornerRadiusComponent;
     type: CornerType;
 };
 
+/** One axis (rx or ry) of a `CornerRadius`: a numeric value, either in units (`'u'`) or as a percentage (`'pct'`). */
 declare type CornerRadiusComponent = {
     value: number;
     unit?: 'pct' | 'u';
 };
 
+/** How a `PacemRectElement` corner is rendered: smoothly `Rounded` or straight-line `Cut` (chamfered). */
 declare enum CornerType {
     Rounded = "rounded",
     Cut = "cut"
 }
 
+/** Event dispatched throughout a `Drawable`'s drag lifecycle, carrying `DragEventArgs`. */
 declare class DragEvent_2 extends UI2DEvent<DragEventArgs> {
 }
 
+/** Event args carried by a `DragEvent`: the dragged `item` and its current `offset`. */
 declare interface DragEventArgs {
     readonly offset: Point;
     readonly item: Drawable;
 }
 
+/** Base contract for anything that can be drawn on a `Stage`. */
 declare interface Drawable {
     stage?: Stage;
     /** Gets or sets whether the drawable is hit-testable. */
@@ -67,17 +81,27 @@ declare interface Drawable {
     tag?: any;
 }
 
+/**
+ * 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).
+ */
 declare abstract class DrawableElement extends Components_2.PacemCrossItemsContainerElement<DrawableElement> implements Drawable {
     validate(_: DrawableElement): boolean;
     protected findContainer(): DrawableElement | Pacem2DElement;
+    /** @readonly Gets the `Pacem2DElement` stage this drawable belongs to. */
     get stage(): Pacem2DElement;
+    /** @readonly Gets the closest ancestor `DrawableElement` (e.g. a containing group), if any. */
     get parent(): DrawableElement;
+    /** Gets or sets a free-form tag, reflected back onto the `tag` attribute. */
     tag: any;
+    /** Gets or sets whether the drawable is hit-testable (when `true`, it is ignored by pointer hit-testing). */
     inert: boolean;
     disconnectedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** Event dispatched for pointer interactions (over/out/down/up/click) targeting a `Drawable`. */
 declare class DrawableEvent extends UI2DEvent<Drawable> {
     constructor(type: string, args: Drawable, originalEvent: MouseEvent | TouchEvent | KeyboardEvent, m: Matrix2D);
 }
@@ -147,22 +171,31 @@ export declare namespace Drawing_2 {
     }
 }
 
+/**
+ * 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.
+ */
 declare function getStageOptions(stage: Stage): StageOptions;
 
+/** Base gradient contract, a sequence of `GradientStop`s. See also `LinearGradient` and `RadialGradient`. */
 declare interface Gradient {
     stops: GradientStop[];
 }
 
+/** A single color stop within a `Gradient`. */
 declare interface GradientStop {
     offset: number;
     color: string;
     opacity?: number;
 }
 
+/** A `UiObject` acting as a container of other `Drawable`s. */
 declare interface Group extends UiObject {
     childDrawables: Drawable[];
 }
 
+/** A `UiObject` rendering a raster image. */
 declare interface Image_2 extends UiObject {
     src: string;
     x?: number;
@@ -171,29 +204,40 @@ declare interface Image_2 extends UiObject {
     height?: number;
 }
 
+/** Type guard telling whether `object` implements `Drawable`. */
 declare function isDrawable(object: any): object is Drawable;
 
+/** Type guard telling whether `object` implements `Group` and has at least one child drawable. */
 declare function isGroup(object: any): object is Group;
 
+/** Type guard telling whether `object` implements `Image`. */
 declare function isImage(object: any): object is Image_2;
 
+/** Type guard telling whether `object` is a `LinearGradient`. */
 declare function isLinearGradient(object: Gradient): object is LinearGradient;
 
+/** Type guard telling whether `object` implements `PresentationObject`. */
 declare function isPresentationObject(object: any): object is PresentationObject;
 
+/** Type guard telling whether `object` is a `RadialGradient`. */
 declare function isRadialGradient(object: Gradient): object is RadialGradient;
 
+/** Type guard telling whether `object` implements `Shape`. */
 declare function isShape(object: any): object is Shape;
 
+/** Type guard telling whether `object` implements `Text`. */
 declare function isText(object: any): object is Text_2;
 
+/** Type guard telling whether `object` implements `UiObject`. */
 declare function isUiObject(object: any): object is UiObject;
 
+/** A gradient that varies linearly from `start` to `end`. */
 declare interface LinearGradient extends Gradient {
     start: Point;
     end: Point;
 }
 
+/** Arrowhead/decoration drawn at a shape's start, end, or intermediate vertices (akin to SVG `<marker>`). */
 declare type Marker = {
     pathData: string;
     stroke?: string;
@@ -204,7 +248,13 @@ declare type Marker = {
     height?: number;
 };
 
+/**
+ * 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.
+ */
 declare abstract class Pacem2DAdapterElement extends PacemEventTarget {
+    /** Fallback stroke/fill/lineWidth values used when a shape doesn't provide its own. */
     protected DefaultShapeValues: {
         stroke: string;
         lineWidth: number;
@@ -247,21 +297,43 @@ declare abstract class Pacem2DAdapterElement extends PacemEventTarget {
      * Processes the stage content and returns an image accordingly.
      * */
     abstract snapshot(stage: Pacem2DElement, bgColor?: string, type?: string, quality?: number): PromiseLike<Blob>;
+    /**
+     * 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).
+     */
     protected snapshotElement(element: HTMLElement | SVGElement, bgColor?: string, type?: string, quality?: number): PromiseLike<Blob>;
 }
 
+/**
+ * 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.
+ */
 declare class Pacem2DElement extends Components_2.PacemItemsContainerElement<DrawableElement> implements Stage_2 {
     #private;
+    /** @readonly Gets the DOM element hosting the stage content. */
     get stage(): HTMLElement;
+    /** Processes the stage content and returns a snapshot image (delegates to the current `adapter`). */
     snapshot(bgColor?: string, type?: string, quality?: number): Promise<any> | PromiseLike<Blob>;
+    /** @readonly Gets the matrix that projects stage coords into screen coords. */
     get transformMatrix(): Matrix2D;
     private _transformMatrixScale;
     validate(item: DrawableElement): boolean;
+    /** Gets or sets the rendering adapter (e.g. `pacem-2d-svg-adapter`) in charge of drawing the stage content. */
     adapter: Pacem2DAdapterElement;
+    /** Gets or sets the visible portion of the stage, in stage coordinates. */
     viewbox: Rect;
+    /** Gets or sets how the viewbox is mapped onto the stage's viewport (mirrors SVG's `preserveAspectRatio`). */
     aspectRatio: ViewBoxAspectRatio;
+    /** Gets or sets the drawable items to render, alternative to declaring them as child elements. */
     datasource: Drawable[];
+    /** Gets or sets the pan/zoom/click interaction options. */
     options: StageOptions;
+    /** Gets or sets the zoom factor (relative to the original viewbox). */
     zoom: number;
     private _stage;
     private _resize;
@@ -287,7 +359,12 @@ declare class Pacem2DElement extends Components_2.PacemItemsContainerElement<Dra
     disconnectedCallback(): void;
 }
 
-/** 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.
+ */
 declare class PacemCanvasAdapterElement extends Pacem2DAdapterElement {
     #private;
     snapshot(stage: Pacem2DElement, backgroundColor?: string, type?: string, quality?: number): PromiseLike<Blob>;
@@ -322,100 +399,184 @@ declare class PacemCanvasAdapterElement extends Pacem2DAdapterElement {
     private _handles;
 }
 
+/** `<pacem-2d-circle>`: renders a full circle, or a pie-slice sector when `start`/`end` are set. */
 declare class PacemCircleElement extends ShapeElement {
+    /** Gets or sets the center point. */
     center: Point;
+    /** Gets or sets the radius. */
     radius: number;
+    /** Gets or sets the sector start angle, in degrees (full circle when `start`/`end` describe a full turn). */
     start: number;
+    /** Gets or sets the sector end angle, in degrees. */
     end: number;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Computes the SVG path data of the circle (or sector) out of its own `center`/`radius`/`start`/`end`. */
     protected getPathData(): string;
     protected getShapeGeometry(): ShapeGeometry;
+    /**
+     * 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?: Point, r?: number, start?: number, end?: number): string;
 }
 
+/** `<pacem-2d-ellipse>`: renders a full ellipse, or a pie-slice sector when `start`/`end` are set. */
 declare class PacemEllipseElement extends ShapeElement {
+    /** Gets or sets the center point. */
     center: Point;
+    /** Gets or sets the horizontal radius. */
     rx: number;
+    /** Gets or sets the vertical radius. */
     ry: number;
+    /** Gets or sets the sector start angle, in degrees (full ellipse when `start`/`end` describe a full turn). */
     start: number;
+    /** Gets or sets the sector end angle, in degrees. */
     end: number;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Computes the SVG path data of the ellipse (or sector) out of its own `center`/`rx`/`ry`/`start`/`end`. */
     protected getPathData(): string;
     protected getShapeGeometry(): ShapeGeometry;
+    /**
+     * 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?: Point, rx?: number, ry?: number, start?: number, end?: number): string;
 }
 
+/** `<pacem-2d-group>`: a container that groups child drawables, applying its own transform/presentation state to all of them. */
 declare class PacemGroupElement extends PresentationElement implements Group {
     #private;
     validate(item: DrawableElement): boolean;
+    /** Gets or sets the child drawables, alternative to declaring them as nested elements. */
     datasource: Drawable[];
+    /** @readonly Gets the child drawables currently in the group. */
     get childDrawables(): Drawable[];
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** `<pacem-2d-image>`: renders a raster image at a given position and size within the stage. */
 declare class PacemImageElement extends UiElement implements Image_2 {
+    /** Gets or sets the image source URL. */
     src: string;
+    /** Gets or sets the horizontal position. */
     x: number;
+    /** Gets or sets the vertical position. */
     y: number;
+    /** Gets or sets the rendered width (defaults to the natural width, scaled if only `height` is set). */
     width: number;
+    /** Gets or sets the rendered height (defaults to the natural height, scaled if only `width` is set). */
     height: number;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** `<pacem-2d-line>`: renders a straight segment between two points. */
 declare class PacemLineElement extends ShapeElement {
+    /** Gets or sets the starting point. */
     from: Point;
+    /** Gets or sets the ending point. */
     to: Point;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     protected getShapeGeometry(): ShapeGeometry;
+    /** Computes the SVG path data of the line out of its own `from`/`to` points. */
     protected getPathData(): string;
+    /** Computes the SVG path data of a straight segment between `from` and `to`. */
     static getPathData(from?: Point, to?: Point): string;
 }
 
+/** `<pacem-2d-path>`: renders an arbitrary SVG path, provided verbatim through the `d` property. */
 declare class PacemPathElement extends ShapeElement {
+    /** Gets or sets the raw SVG path data (`d` attribute syntax). */
     d: string;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Returns the raw path data, i.e. `d`. */
     protected getPathData: () => string;
     protected getShapeGeometry(): ShapeGeometry;
 }
 
+/** `<pacem-2d-polygon>`: renders a regular polygon (or, with `starIndent` set, a star) centered on `center`. */
 declare class PacemPolygonElement extends ShapeElement {
+    /** Gets or sets the number of sides (or points, for a star) of the polygon. */
     sides: number;
     /** The circumradius of the polygon. */
     radius: number;
+    /** Gets or sets the center point of the polygon. */
     center: Point;
+    /** Gets or sets the star indentation factor (0 = regular polygon, up to 1 = fully indented star). */
     starIndent: number;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Computes the SVG path data of the polygon out of its own `center`, `radius`, `sides` and `starIndent`. */
     protected getPathData(): string;
     protected getShapeGeometry(): ShapeGeometry;
+    /**
+     * 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: Point, radius: number, sides: number, starIndent?: number): ShapeGeometry;
+    /** Computes the SVG path data of a regular polygon or star. See `getShapeGeometry` for the parameters. */
     static getPathData(center: Point, radius: number, sides: number, starIndent?: number): string;
 }
 
+/** `<pacem-2d-polyline>`: renders a series of connected segments through `points`, optionally `closed` into a polygon. */
 declare class PacemPolylineElement extends ShapeElement {
+    /** Gets or sets the vertices of the polyline, in order. */
     points: Point[];
+    /** Gets or sets whether the polyline is closed back onto its first point. */
     closed: boolean;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /**
+     * 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: Point[], closed: boolean): ShapeGeometry;
     protected getShapeGeometry(): ShapeGeometry;
+    /** Computes the SVG path data of the polyline out of its own `points`/`closed`. */
     protected getPathData(): string;
+    /** Computes the SVG path data of a polyline. See `getShapeGeometry` for the parameters. */
     static getPathData(points: Point[], closed: boolean): string;
 }
 
+/** `<pacem-2d-rect>`: renders a rectangle, optionally with independently rounded or cut corners. */
 declare class PacemRectElement extends ShapeElement {
+    /** Gets or sets the horizontal position of the top-left corner. */
     x: number;
+    /** Gets or sets the vertical position of the top-left corner. */
     y: number;
+    /** Gets or sets the width. */
     w: number;
+    /** Gets or sets the height. */
     h: number;
+    /** Gets or sets the per-corner radii (single value applies to all four corners, or one `CornerRadius` per corner: top-left, top-right, bottom-right, bottom-left). */
     r: [CornerRadius, CornerRadius, CornerRadius, CornerRadius];
+    /** Gets or sets the default corner treatment (rounded or cut) used when `r` provides plain numbers instead of `CornerRadius` objects. */
     cornerType: CornerType;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
+    /** Computes the SVG path data of the rectangle out of its own `x`/`y`/`w`/`h`/`r`/`cornerType`. */
     protected getPathData(): string;
     protected getShapeGeometry(): ShapeGeometry;
+    /** Computes the SVG path data of a plain rectangle (no rounding). */
     static getPathData(x: number, y: number, w: number, h: number): string;
+    /** Computes the SVG path data of a rectangle whose four corners share the same `CornerRadius`. */
     static getPathData(x: number, y: number, w: number, h: number, r: CornerRadius): string;
+    /** Computes the SVG path data of a rectangle with independent per-corner radii (top-left, top-right, bottom-right, bottom-left). */
     static getPathData(x: number, y: number, w: number, h: number, r: [CornerRadius, CornerRadius, CornerRadius, CornerRadius]): string;
 }
 
+/**
+ * `<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.
+ */
 declare class PacemSvgAdapterElement extends Pacem2DAdapterElement {
     #private;
     snapshot(stage: Stage, background?: string, type?: string, quality?: number): PromiseLike<Blob>;
@@ -447,31 +608,52 @@ declare class PacemSvgAdapterElement extends Pacem2DAdapterElement {
     private _items;
 }
 
+/** `<pacem-2d-text>`: renders a text label anchored at a given point. */
 declare class PacemTextElement extends UiElement implements Text_2 {
+    /** Gets or sets the text content to render. */
     text: string;
+    /** Gets or sets the text color. */
     color: string;
+    /** Gets or sets the font family. */
     fontFamily: string;
+    /** Gets or sets the font size, in pixels. */
     fontSize: number;
+    /** Gets or sets the font weight. */
     fontWeight: string;
+    /** Gets or sets the font style (e.g. `italic`). */
     fontStyle: string;
+    /** Gets or sets the point the text is anchored to. */
     anchor: Point;
+    /** Gets or sets the horizontal text alignment relative to `anchor`. */
     textAnchor: 'start' | 'middle' | 'end';
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/**
+ * 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`.
+ */
 declare abstract class PresentationElement extends UiElement implements PresentationObject {
+    /** Gets or sets the stroke color. */
     stroke: string;
+    /** Gets or sets the fill, either a color string or a `Gradient`. */
     fill: string | Gradient;
+    /** Gets or sets the stroke dash pattern, as an array of segment lengths. */
     dashArray?: number[];
+    /** Gets or sets the stroke line width. */
     lineWidth: number;
+    /** Gets or sets the stroke line join style. */
     lineJoin?: CanvasLineJoin;
+    /** Gets or sets the stroke line cap style. */
     lineCap?: CanvasLineCap;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
 }
 
+/** A `UiObject` that also carries presentation state (stroke, fill, etc.). */
 declare interface PresentationObject extends UiObject, PresentationState {
 }
 
+/** Snapshot of the presentation-related state (stroke, fill, transform, opacity) applicable to a drawable. */
 declare interface PresentationState {
     stroke?: string;
     lineWidth?: number;
@@ -483,15 +665,25 @@ declare interface PresentationState {
     opacity?: number;
 }
 
+/** Static helpers to combine `PresentationState` instances (e.g. a shape's own state with its inherited parent state). */
 declare 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: PresentationState, rhs: PresentationState, precomputedMatrix?: Matrix2D): PresentationState;
 }
 
+/** A gradient that radiates from `center` outwards up to `radius`. */
 declare interface RadialGradient extends Gradient {
     center: Point;
     radius: number;
 }
 
+/** A `PresentationObject` whose visual is defined by an SVG path, optionally decorated with markers. */
 declare interface Shape extends PresentationObject {
     pathData: string;
     markerStart?: Marker;
@@ -501,44 +693,68 @@ declare interface Shape extends PresentationObject {
     readonly boundingRect?: Rect;
 }
 
+/** Static helper to build an empty `ShapeGeometry`. */
 declare class Shape {
+    /** Returns an empty `ShapeGeometry` (no path, no vertices, zero-sized bounding rect). */
     static empty(): ShapeGeometry;
 }
 
+/**
+ * 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.
+ */
 declare abstract class ShapeElement extends PresentationElement implements Shape {
     #private;
+    /** @readonly Gets the computed SVG path data backing the shape (recomputed via `recomputeShape`). */
     protected data: string;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
     viewActivatedCallback(): void;
+    /** Recomputes `data`, `vertices` and `boundingRect` from `getShapeGeometry()`. */
     protected recomputeShape(): void;
+    /** @readonly Gets the SVG path data backing the shape. */
     get pathData(): string;
+    /** @readonly Gets the bounding rectangle of the shape. */
     get boundingRect(): Rect;
+    /** @readonly Gets the vertices making up the shape. */
     get vertices(): Point[];
+    /** Computes the path data, vertices and bounding rect out of the shape's own geometry properties. */
     protected abstract getShapeGeometry(): ShapeGeometry;
 }
 
+/** Computed geometry of a shape: its SVG path data, its vertices and its bounding rectangle. */
 declare type ShapeGeometry = {
     pathData: string;
     vertices: Point[];
     boundingRect: Rect;
 };
 
+/** Abstraction of a 2D drawing surface capable of (re)drawing `Drawable` items and exposing its viewbox and screen transform. */
 declare interface Stage extends EventTarget {
+    /** Draws (or redraws) the whole stage, or just the provided item. */
     draw(item?: Drawable): any;
+    /** Gets or sets the visible portion of the stage, in stage coordinates. */
     viewbox: Rect;
+    /** Gets or sets how the viewbox is mapped onto the stage's viewport. */
     aspectRatio?: ViewBoxAspectRatio;
+    /** @readonly Gets the matrix that projects stage coords into screen coords. */
     readonly transformMatrix: Matrix2D;
+    /** @readonly Gets the DOM element hosting the stage content. */
     readonly stage: HTMLElement;
 }
 
+/** A drawing `Stage` bound to a rendering `Pacem2DAdapterElement` (SVG or Canvas). */
 declare interface Stage_2 extends Stage {
+    /** @readonly Gets the adapter in charge of rendering this stage. */
     readonly adapter: Pacem2DAdapterElement;
 }
 
+/** Event dispatched for pointer interactions (move/down/up/click) targeting a `Stage` at large (i.e. no specific hit `Drawable`). */
 declare class StageEvent extends UI2DEvent<Stage> {
     constructor(type: string, args: Stage, originalEvent: MouseEvent | TouchEvent | KeyboardEvent, m?: Matrix2D);
 }
 
+/** User-interaction options (pan/zoom/click) of a `Stage`, including the key modifiers required to trigger them. */
 declare type StageOptions = {
     panControl: boolean;
     zoomControl: boolean;
@@ -547,6 +763,7 @@ declare type StageOptions = {
     clickModifiers: EventKeyModifier[];
 };
 
+/** A `UiObject` rendering a piece of text. */
 declare interface Text_2 extends UiObject {
     text: string;
     fontFamily?: string;
@@ -558,21 +775,36 @@ declare interface Text_2 extends UiObject {
     textAnchor?: 'start' | 'middle' | 'end';
 }
 
+/**
+ * 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.
+ */
 declare abstract class UI2DEvent<T> extends CustomUIEvent<T> {
     #private;
     constructor(type: string, eventInit: CustomEventInit<T>, originalEvent: MouseEvent | TouchEvent | KeyboardEvent, transformMatrix: Matrix2D);
     /** Gets the screen transform matrix. */
     get transformMatrix(): Matrix2D;
+    /** Projects a point (defaults to the event's screen coordinates) through the event's transform matrix. */
     project(pt?: Point): Point;
 }
 
+/**
+ * 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`.
+ */
 declare abstract class UiElement extends DrawableElement implements UiObject {
     #private;
+    /** Gets or sets the rotation angle, in degrees. */
     rotate: number;
+    /** Gets or sets the horizontal scale factor. */
     scaleX: number;
+    /** Gets or sets the vertical scale factor. */
     scaleY: number;
+    /** Gets or sets the horizontal translation offset. */
     translateX: number;
+    /** Gets or sets the vertical translation offset. */
     translateY: number;
+    /** Gets or sets the opacity, in the `[0, 1]` range. */
     opacity: number;
     viewActivatedCallback(): void;
     propertyChangedCallback(name: string, old: any, val: any, first?: boolean): void;
@@ -588,13 +820,16 @@ declare abstract class UiElement extends DrawableElement implements UiObject {
     };
 }
 
+/** A `Drawable` participating in the 2D transform pipeline (opacity and transform matrix). */
 declare interface UiObject extends Drawable {
     opacity?: number;
     readonly transformMatrix?: Matrix2D;
 }
 
+/** Alignment keyword along one axis of the viewbox-to-viewport mapping (mirrors SVG's `preserveAspectRatio`). */
 declare type ViewBoxAlignment = 'min' | 'mid' | 'max';
 
+/** Aspect-ratio behavior of the viewbox-to-viewport mapping: `'none'` stretches to fit, otherwise alignment plus an optional `slice` (cover) vs. `meet` (contain) choice. */
 declare type ViewBoxAspectRatio = 'none' | {
     x: ViewBoxAlignment;
     y: ViewBoxAlignment;