@neptune3d/dom 0.0.10 → 0.0.11

package/dist/index.d.ts

@@ -291,6 +291,38 @@ type InputElementMap = {
  * Includes keyword-based directions (e.g., "to right") and angle-based values (e.g., "45deg").
  */
 type LinearGradientDirection = "to top" | "to top right" | "to right top" | "to right" | "to bottom right" | "to right bottom" | "to bottom" | "to bottom left" | "to left bottom" | "to left" | "to top left" | "to left top" | `${number}deg` | `${number}grad` | `${number}rad` | `${number}turn`;
+/**
+ * Declarative type for building a Content Security Policy.
+ * Each directive maps to a space-separated string of sources or values.
+ */
+interface ContentSecurityPolicy {
+  "default-src"?: string;
+  "script-src"?: string;
+  "style-src"?: string;
+  "img-src"?: string;
+  "font-src"?: string;
+  "connect-src"?: string;
+  "media-src"?: string;
+  "object-src"?: string;
+  "frame-src"?: string;
+  "child-src"?: string;
+  "worker-src"?: string;
+  "manifest-src"?: string;
+  "prefetch-src"?: string;
+  "form-action"?: string;
+  "base-uri"?: string;
+  "frame-ancestors"?: string;
+  "navigate-to"?: string;
+  "require-trusted-types-for"?: string;
+  "trusted-types"?: string;
+  sandbox?: string;
+  "upgrade-insecure-requests"?: string;
+  "block-all-mixed-content"?: string;
+  "report-uri"?: string;
+  "report-to"?: string;
+}
+type IFrameSandboxFlag = "allow-forms" | "allow-modals" | "allow-orientation-lock" | "allow-pointer-lock" | "allow-popups" | "allow-popups-to-escape-sandbox" | "allow-presentation" | "allow-same-origin" | "allow-scripts" | "allow-storage-access-by-user-activation" | "allow-top-navigation" | "allow-top-navigation-by-user-activation";
+type TextAreaWrapMode = "soft" | "hard" | "off";
 //#endregion
 //#region src/BaseStyle.d.ts
 declare abstract class BaseStyle {
@@ -1208,6 +1240,54 @@ declare abstract class BaseStyle {
    * @return This instance for chaining.
    */
   outlineColor(value: Property.OutlineColor | undefined): this;
+  /**
+   * Sets the `outline-offset` style of the element.
+   * Controls the space between the outline and the element's edge.
+   * Accepts length units (e.g. px, em, rem) or CSS variables.
+   * Passing `undefined` removes the outline-offset style.
+   *
+   * @param value - The offset distance to apply, or `undefined` to remove it.
+   * @return This instance for chaining.
+   */
+  outlineOffset(value: Property.OutlineOffset | undefined): this;
+  /**
+   * Sets the `line-height` of the element.
+   * Controls vertical spacing between lines of text. Accepts unitless numbers, length units, percentages, or CSS variables.
+   * Passing `undefined` removes the line-height style.
+   *
+   * @param value - The line-height to apply, or `undefined` to remove it.
+   * @return This instance for chaining.
+   */
+  lineHeight(value: Property.LineHeight | undefined): this;
+  /**
+   * Sets the `word-wrap` style of the element.
+   * Controls how long words or URLs break and wrap within the container.
+   * Accepts values like `"normal"`, `"break-word"`, or CSS variables.
+   * Passing `undefined` removes the word-wrap style.
+   *
+   * @param value - The word-wrap value to apply, or `undefined` to remove it.
+   * @return This instance for chaining.
+   */
+  wordWrap(value: Property.WordWrap | undefined): this;
+  /**
+   * Sets the `tab-size` style of the element.
+   * Controls the visual width of tab characters in spaces. Accepts unitless numbers or CSS variables.
+   * Passing `undefined` removes the tab-size style.
+   *
+   * @param value - The tab size to apply, or `undefined` to remove it.
+   * @return This instance for chaining.
+   */
+  tabSize(value: Property.TabSize | undefined): this;
+  /**
+   * Sets the `resize` style of the element.
+   * Controls whether and how the element is resizable by the user.
+   * Accepts values like `"none"`, `"both"`, `"horizontal"`, `"vertical"`, or CSS variables.
+   * Passing `undefined` removes the resize style.
+   *
+   * @param value - The resize behavior to apply, or `undefined` to remove it.
+   * @return This instance for chaining.
+   */
+  resize(value: Property.Resize | undefined): this;
   /**
    * Applies CSS styles to truncate overflowing text with an ellipsis.
    * Ensures the text stays on a single line and hides overflow.
@@ -1283,6 +1363,136 @@ declare abstract class BaseDom<E extends HTMLElement | SVGElement> extends BaseS
    * @return The computed style object for this element.
    */
   getComputedStyle(): CSSStyleDeclaration;
+  /**
+   * Returns the child element at the specified index.
+   * Uses `children`, which excludes text, comment, and other non-element nodes.
+   * Returns `null` if the index is out of bounds.
+   *
+   * @param index - The zero-based index of the child element.
+   * @return The child `Element` at the given index, or `null` if not found.
+   */
+  getChildAt(index: number): Element | null;
+  /**
+   * Returns the child node at the specified index.
+   * Uses `childNodes`, which includes elements, text nodes, comments, and other node types.
+   * Returns `null` if the index is out of bounds.
+   *
+   * @param index - The zero-based index of the child node.
+   * @return The child `Node` at the given index, or `null` if not found.
+   */
+  getNodeAt(index: number): Node | null;
+  /**
+   * Returns a static array of all child elements.
+   * Excludes text nodes, comments, and other non-element nodes.
+   * Useful for DOM traversal, filtering, or batch operations.
+   *
+   * @return An array of child `Element` nodes.
+   */
+  getChildren(): Element[];
+  /**
+   * Returns a static array of all child nodes.
+   * Includes elements, text nodes, comments, and other node types.
+   * Useful for low-level DOM inspection or mixed-content manipulation.
+   *
+   * @return An array of child `Node` instances.
+   */
+  getNodes(): Node[];
+  /**
+   * Gets the textContent property of the DOM element.
+   */
+  getText(): string;
+  /**
+   * Retrieves the value of a single attribute.
+   * @param name - The attribute name to read (e.g. "aria-label", "role").
+   * @return The attribute value as a string, or null if not present.
+   */
+  getAttr(name: string): string | null;
+  /**
+   * Retrieves the value of a single property.
+   * @param name - The property name to read (e.g. "value", "checked", "disabled").
+   * @return The property value, or undefined if not present.
+   */
+  getProp(name: string): any;
+  /**
+   * Checks whether the element has the specified CSS class.
+   * Useful for conditional logic, toggling, or state inspection.
+   *
+   * @param name - The class name to check.
+   * @return `true` if the class is present, otherwise `false`.
+   */
+  hasClass(name: string): boolean;
+  /**
+   * Sets the `textContent` of the element using any value.
+   * If the value is `null` or `undefined`, clears the content.
+   * Otherwise, converts the value to a string and assigns it.
+   * Useful for rendering dynamic values safely, including numbers, booleans, or objects.
+   *
+   * @param value - The value to assign as plain text, or `null`/`undefined` to clear.
+   * @return This instance for chaining.
+   */
+  text(value: any): this;
+  /**
+   * Sets the `innerHTML` of the element.
+   * Replaces all existing child nodes with the provided HTML string.
+   * Useful for injecting markup, templated content, or resetting the DOM structure.
+   *
+   * @param content - The HTML string to assign as the element's inner content.
+   * @return This instance for chaining.
+   */
+  html(content: string): this;
+  /**
+   * Sets or removes the `id` of the element.
+   * Passing `undefined` clears the ID by setting it to an empty string.
+   *
+   * @param value - The element's ID, or `undefined` to remove it.
+   * @return This DomElement instance for chaining.
+   */
+  id(value: string | undefined): this;
+  /**
+   * Sets a single attribute on the element.
+   * For boolean attributes (e.g. "disabled", "checked"), presence alone determines truthiness.
+   * If `value` is `true`, the attribute is added with no value.
+   * If `value` is `false` or `undefined`, the attribute is removed.
+   *
+   * @param name - The attribute name (e.g. "aria-label", "role", "disabled").
+   * @param value - The attribute value. If `undefined` or `false`, the attribute is removed.
+   * @return This DomElement instance for chaining.
+   */
+  attr(name: string, value: string | number | boolean | undefined): this;
+  /**
+   * Sets multiple attributes on the element.
+   * Delegates to `.attr()` for each key-value pair to ensure consistent handling.
+   *
+   * @param map - A record of attribute names and values.
+   * @return This instance for chaining.
+   */
+  attrs(map: Record<string, string | number | boolean | undefined>): this;
+  /**
+   * Toggles the presence of a boolean attribute on the element.
+   * Uses the native `toggleAttribute` method for clarity and correctness.
+   * If `force` is `true`, ensures the attribute is present.
+   * If `force` is `false`, ensures the attribute is removed.
+   * If `force` is omitted, toggles the current state.
+   *
+   * @param name - The attribute name (e.g. "disabled", "checked", "readonly").
+   * @param force - Optional boolean to force add (`true`) or remove (`false`) the attribute.
+   * @return This instance for chaining.
+   */
+  toggleAttr(name: string, force?: boolean): this;
+  /**
+   * Sets a single property on the element.
+   * @param name - The property name (e.g. "checked", "value", "disabled").
+   * @param value - The property value. If undefined, the property is deleted.
+   * @return This DomElement instance for chaining.
+   */
+  prop(name: string, value: any): this;
+  /**
+   * Sets multiple properties on the element.
+   * @param props - An object mapping property names to values.
+   *                     Properties with undefined values are deleted.
+   * @return This DomElement instance for chaining.
+   */
+  props(props: Record<string, any>): this;
   /**
    * Sets or removes the user-defined class name and applies it alongside the internal CSS class.
    * Uses `setAttribute("class", ...)` for both HTML and SVG elements.
@@ -1359,15 +1569,22 @@ declare abstract class BaseDom<E extends HTMLElement | SVGElement> extends BaseS
    * @return This DomElement instance.
    */
   setChildrenFromIndex(index: number, ...nodes: DomElementChild[]): this;
+  /**
+   * Removes all child nodes from the element by doing `dom.textContent = ""`.
+   *
+   * @return This instance for chaining.
+   */
+  clear(): this;
   /**
    * Removes child elements within the specified index range.
-   * If no range is provided, removes all children.
+   * Behaves like `Array.prototype.slice(from, to)` — `from` is inclusive, `to` is exclusive.
+   * If `from` is omitted, defaults to 0. If `to` is omitted, removes to the end.
    *
    * @param from - The starting index (inclusive). Defaults to 0.
-   * @param to - The ending index (exclusive). Defaults to all children.
-   * @returns This DomElement instance.
+   * @param to - The ending index (exclusive). Defaults to all remaining children.
+   * @return This instance for chaining.
    */
-  clear(from?: number, to?: number): this;
+  clearRange(from?: number, to?: number): this;
   /**
    * Checks whether this element contains the given target node.
    * Accepts either a raw DOM node or another `BaseDom` instance.
@@ -1378,6 +1595,16 @@ declare abstract class BaseDom<E extends HTMLElement | SVGElement> extends BaseS
    * @return `true` if this element contains the target, otherwise `false`.
    */
   contains(target: Node | BaseDom<any>): boolean;
+  /**
+   * Queries this element's subtree for a single matching descendant and wraps it in a `DomElement`.
+   * Returns `null` if no match is found.
+   *
+   * This enables fluent DOM composition and manipulation within scoped components.
+   *
+   * @param selector - A valid CSS selector string.
+   * @return A `DomElement` wrapper for the matched element, or `null` if not found.
+   */
+  query<T extends keyof DomElementTagNameMap>(selector: string): DomElement<T> | null;
   ref(refFn: (el: this) => void): this;
   protected resolveNode(child: DomElementChild): Node;
   protected setStyleProp(name: Autocomplete<keyof CssProperties>, value: string | number | undefined): this;
@@ -1435,19 +1662,6 @@ declare class DomElement<Tag extends keyof DomElementTagNameMap = keyof DomEleme
    * This will be either an `HTMLElement` or `SVGElement` depending on the tag.
    */
   get dom(): DomElementTagNameMap[Tag];
-  /**
-   * Gets the textContent property of the DOM element.
-   */
-  getText(): string;
-  /**
-   * Sets or clears the text content of the element.
-   * Converts any value to a string before assignment.
-   * Passing `undefined` or `null` removes the text by setting it to an empty string.
-   *
-   * @param value - The text content to set, or `undefined`/`null` to clear it.
-   * @return This DomElement instance for chaining.
-   */
-  text(value: any): this;
   /**
    * Removes the element from the DOM tree.
    * Equivalent to calling `element.remove()` on the native DOM node.
@@ -1457,54 +1671,6 @@ declare class DomElement<Tag extends keyof DomElementTagNameMap = keyof DomEleme
    * @return This DomElement instance for chaining.
    */
   remove(): void;
-  /**
-   * Retrieves the value of a single attribute.
-   * @param name - The attribute name to read (e.g. "aria-label", "role").
-   * @return The attribute value as a string, or null if not present.
-   */
-  getAttr(name: string): string | null;
-  /**
-   * Sets a single attribute on the element.
-   * @param name - The attribute name (e.g. "aria-label", "role", "disabled").
-   * @param value - The attribute value. If undefined, the attribute is removed.
-   * @return This DomElement instance for chaining.
-   */
-  attr(name: string, value: string | number | boolean | undefined): this;
-  /**
-   * Sets multiple attributes on the element.
-   * @param attributes - An object mapping attribute names to values.
-   *                     Attributes with undefined values are removed.
-   * @return This DomElement instance for chaining.
-   */
-  attrs(attributes: Record<string, string | number | boolean | undefined>): this;
-  /**
-   * Retrieves the value of a single property.
-   * @param name - The property name to read (e.g. "value", "checked", "disabled").
-   * @return The property value, or undefined if not present.
-   */
-  getProp(name: string): any;
-  /**
-   * Sets a single property on the element.
-   * @param name - The property name (e.g. "checked", "value", "disabled").
-   * @param value - The property value. If undefined, the property is deleted.
-   * @return This DomElement instance for chaining.
-   */
-  prop(name: string, value: any): this;
-  /**
-   * Sets multiple properties on the element.
-   * @param props - An object mapping property names to values.
-   *                     Properties with undefined values are deleted.
-   * @return This DomElement instance for chaining.
-   */
-  props(props: Record<string, any>): this;
-  /**
-   * Sets or removes the `id` of the element.
-   * Passing `undefined` clears the ID by setting it to an empty string.
-   *
-   * @param value - The element's ID, or `undefined` to remove it.
-   * @return This DomElement instance for chaining.
-   */
-  id(value: string | undefined): this;
   /**
    * Sets or removes the `htmlFor` property on a <label> element.
    * This links the label to a form control by its ID.
@@ -1526,9 +1692,10 @@ declare class DomElement<Tag extends keyof DomElementTagNameMap = keyof DomEleme
   title(value: string | undefined): this;
   /**
    * Sets or removes the `disabled` attribute on the element.
-   * Applicable to form controls like <button>, <input>, <select>, etc.
+   * Applicable to form controls like `<button>`, `<input>`, `<select>`, etc.
+   * Passing `true` sets the attribute; `false` removes it.
    *
-   * @param value - If true, sets the `disabled` attribute; if false, removes it.
+   * @param value - Whether the element should be disabled.
    * @return This DomElement instance for chaining.
    */
   disabled(value: boolean): this;
@@ -1545,17 +1712,41 @@ declare class DomElement<Tag extends keyof DomElementTagNameMap = keyof DomEleme
   enable(): this;
   /**
    * Sets or removes the `popover` attribute on the element.
-   * Applies to HTML elements that support the popover API (e.g., `<div popover>`).
+   * Applies to HTML elements that support the Popover API (e.g., `<div popover>`).
    * Passing `undefined` removes the attribute.
    *
-   * Common values include:
+   * Supported values:
    * - `"auto"` → Automatically shows/hides based on user interaction.
    * - `"manual"` → Requires explicit show/hide via JavaScript.
+   * - `"hint"` → Lightweight tooltip-style popover (shown on hover/focus).
+   *
+   * @param value - The popover mode (`"auto"`, `"manual"`, or `"hint"`), or `undefined` to remove it.
+   * @return This DomElement instance for chaining.
+   */
+  popover(value: "auto" | "manual" | "hint" | undefined): this;
+  /**
+   * Sets or removes the `popovertarget` attribute on the element.
+   * This links the element to a popover by ID, allowing it to trigger or control that popover.
+   * Passing `undefined` removes the attribute.
+   *
+   * @param value - The ID of the target popover element, or `undefined` to remove the attribute.
+   * @return This DomElement instance for chaining.
+   */
+  popoverTarget(value: string | undefined): this;
+  /**
+   * Sets or removes the `popovertargetaction` attribute on the element.
+   * This defines the action to perform on the target popover when the element is activated.
+   * Pass `undefined` to remove the attribute.
+   *
+   * Valid values:
+   * - `"show"` → Opens the target popover.
+   * - `"hide"` → Closes the target popover.
+   * - `"toggle"` → Toggles the target popover.
    *
-   * @param value - The popover mode (`"auto"` or `"manual"`), or `undefined` to remove it.
+   * @param value - The action to apply, or `undefined` to remove the attribute.
    * @return This DomElement instance for chaining.
    */
-  popover(value: "auto" | "manual" | undefined): this;
+  popoverTargetAction(value: "show" | "hide" | "toggle" | undefined): this;
   /**
    * Shows the popover on this element.
    * Requires the element to have a `popover="manual"` attribute and be in the DOM.
@@ -1578,12 +1769,15 @@ declare class DomElement<Tag extends keyof DomElementTagNameMap = keyof DomEleme
  */
 declare function $<T$1 extends keyof DomElementTagNameMap>(tag: T$1): DomElement<T$1>;
 /**
- * Queries the DOM for a matching element and wraps it in a DomElement.
+ * Queries the DOM for a matching element and wraps it in a `DomElement`.
+ * Returns `null` if no element matches the selector.
+ *
+ * This enables fluent manipulation using your custom DOM API.
+ *
  * @param selector - A CSS selector string to locate the element.
- * @return A DomElement wrapping the matched element.
- * @throws If no element matches the selector, this will throw due to non-null assertion.
+ * @return A `DomElement` wrapping the matched element, or `null` if not found.
  */
-declare function $query<T$1 extends keyof DomElementTagNameMap>(selector: string): DomElement<T$1>;
+declare function $query<T$1 extends keyof DomElementTagNameMap>(selector: string): DomElement<T$1> | null;
 //#endregion
 //#region src/AnchorElement.d.ts
 declare class AnchorElement extends DomElement<"a"> {
@@ -1592,6 +1786,144 @@ declare class AnchorElement extends DomElement<"a"> {
 }
 declare function $a(): AnchorElement;
 //#endregion
+//#region src/BaseSvgElement.d.ts
+/**
+ * Base class for SVG shape elements, providing fluent setters for common SVG attributes.
+ *
+ * Extends `DomElement<T>` with ergonomic methods for styling (`fill`, `stroke`, `opacity`)
+ * and geometric transforms (`translate`, `rotate`, `scale`), ensuring consistency across
+ * all SVG element wrappers (e.g. `<path>`, `<rect>`, `<circle>`, etc.).
+ *
+ * Intended to be subclassed by specific SVG element wrappers like `SvgPath`, `SvgRect`, etc.
+ *
+ * @typeParam T - The SVG tag name (e.g. "path", "rect", "circle") this element represents.
+ */
+declare class BaseSvgElement<T$1 extends keyof SvgElementTagNameMap> extends DomElement<T$1> {
+  /**
+   * Sets the `fill` color.
+   * @param color - Fill color (e.g. "red", "#ff0000", "none").
+   * @return This instance for chaining.
+   */
+  svgFill(color: string): this;
+  /**
+   * Sets the `fill-rule` property.
+   * Determines how the interior of a shape is determined when paths intersect.
+   *
+   * @param rule - One of "nonzero" or "evenodd".
+   * @return This instance for chaining.
+   */
+  fillRule(rule: "nonzero" | "evenodd"): this;
+  /**
+   * Sets the `stroke` color.
+   * @param color - Stroke color (e.g. "black", "#000", "none").
+   * @return This instance for chaining.
+   */
+  svgStroke(color: string): this;
+  /**
+   * Sets the `stroke-width` value.
+   * @param width - Stroke width in pixels or units.
+   * @return This instance for chaining.
+   */
+  svgStrokeWidth(width: number | string): this;
+  /**
+   * Sets the `stroke-linejoin` style.
+   * Controls how two connected segments in a stroke join.
+   *
+   * @param value - One of "miter", "round", or "bevel".
+   * @return This instance for chaining.
+   */
+  strokeLinejoin(value: "miter" | "round" | "bevel"): this;
+  /**
+   * Sets the `stroke-linecap` style.
+   * Controls how the end of an open stroke is rendered.
+   *
+   * @param value - One of "butt", "round", or "square".
+   * @return This instance for chaining.
+   */
+  strokeLinecap(value: "butt" | "round" | "square"): this;
+  /**
+   * Sets the `stroke-miterlimit` value.
+   * Controls the maximum allowed ratio of miter length to stroke width for miter joins.
+   *
+   * @param value - Miter limit (typically ≥ 1).
+   * @return This instance for chaining.
+   */
+  strokeMiterlimit(value: number): this;
+  /**
+   * Sets the `opacity` value.
+   * @param value - Opacity from 0 to 1.
+   * @return This instance for chaining.
+   */
+  svgOpacity(value: number): this;
+  /**
+   * Sets the `transform` attribute with a raw SVG transform string.
+   * Accepts any valid transform function: translate, rotate, scale, skewX, skewY, matrix.
+   *
+   * @param value - SVG transform string (e.g. "translate(10, 20) rotate(45)").
+   * @return This instance for chaining.
+   */
+  svgTransform(value: string): this;
+  /**
+   * Applies a `translate(x, y)` transform to the element.
+   * Sets the `transform` attribute, replacing any existing value.
+   *
+   * @param x - Horizontal translation in user units.
+   * @param y - Vertical translation in user units.
+   * @return This instance for chaining.
+   */
+  svgTranslate(x: number, y: number): this;
+  /**
+   * Applies a horizontal `translate(x, 0)` transform to the element.
+   * Sets the `transform` attribute, replacing any existing value.
+   *
+   * @param x - Horizontal translation in user units.
+   * @return This instance for chaining.
+   */
+  svgTranslateX(x: number): this;
+  /**
+   * Applies a vertical `translate(0, y)` transform to the element.
+   * Sets the `transform` attribute, replacing any existing value.
+   *
+   * @param y - Vertical translation in user units.
+   * @return This instance for chaining.
+   */
+  svgTranslateY(y: number): this;
+  /**
+   * Applies a `rotate(angle)` or `rotate(angle, cx, cy)` transform to the element.
+   * Sets the `transform` attribute, replacing any existing value.
+   *
+   * @param angle - Rotation angle in degrees.
+   * @param cx - Optional x coordinate of the rotation center.
+   * @param cy - Optional y coordinate of the rotation center.
+   * @return This instance for chaining.
+   */
+  svgRotate(angle: number, cx?: number, cy?: number): this;
+  /**
+   * Applies a uniform `scale(s)` transform to the element.
+   * Sets the `transform` attribute, replacing any existing value.
+   *
+   * @param s - Uniform scale factor for both x and y axes.
+   * @return This instance for chaining.
+   */
+  svgScale(s: number): this;
+  /**
+   * Applies a horizontal `scale(sx, 1)` transform to the element.
+   * Sets the `transform` attribute, replacing any existing value.
+   *
+   * @param sx - Horizontal scale factor.
+   * @return This instance for chaining.
+   */
+  svgScaleX(sx: number): this;
+  /**
+   * Applies a vertical `scale(1, sy)` transform to the element.
+   * Sets the `transform` attribute, replacing any existing value.
+   *
+   * @param sy - Vertical scale factor.
+   * @return This instance for chaining.
+   */
+  svgScaleY(sy: number): this;
+}
+//#endregion
 //#region src/Button.d.ts
 declare class Button extends DomElement<"button"> {
   constructor();
@@ -1878,10 +2210,18 @@ declare class CssRule extends BaseStyle {
 //#endregion
 //#region src/DomBody.d.ts
 /**
- * Wrapper for document.body with style and DOM composition utilities.
- * Enables fluent styling and child node management.
+ * Wrapper for a `<body>` element with style and DOM composition utilities.
+ * Accepts any `HTMLBodyElement`, including from iframes or synthetic documents.
  */
 declare class DomBody extends BaseDom<HTMLBodyElement> {
+  constructor(body: HTMLBodyElement);
+  protected _body: HTMLBodyElement;
+  /**
+   * Returns the underlying `<body>` element wrapped by this `DomBody` instance.
+   * Enables direct DOM access for interoperability with native APIs or manual manipulation.
+   *
+   * @return The wrapped `HTMLBodyElement`.
+   */
   get dom(): HTMLBodyElement;
 }
 /**
@@ -1892,20 +2232,157 @@ declare class DomBody extends BaseDom<HTMLBodyElement> {
  *
  * @return A DomBody instance wrapping `document.body`.
  */
-declare function $body(): DomBody;
+declare function $body(body?: HTMLBodyElement): DomBody;
 //#endregion
-//#region src/DomDocument.d.ts
+//#region src/DomHead.d.ts
 /**
- * Wrapper for the global `document` object with typed event listener utilities.
- * Useful for managing document-level events like visibility changes, selection, or clipboard interactions.
+ * Wrapper for a `<head>` element with style and DOM composition utilities.
+ * Accepts any `HTMLHeadElement`, including from iframes or synthetic documents.
  */
-declare class DomDocument {
+declare class DomHead extends BaseDom<HTMLHeadElement> {
+  constructor(head: HTMLHeadElement);
+  protected _head: HTMLHeadElement;
   /**
-   * Adds an event listener to the document.
-   * @param type - The event type (e.g., "visibilitychange", "copy", "selectionchange").
-   * @param handler - The event handler function.
-   * @param options - Optional event listener options.
-   * @return This instance for chaining.
+   * Returns the underlying `<head>` element wrapped by this `DomHead` instance.
+   * Enables direct DOM access for interoperability with native APIs or manual manipulation.
+   *
+   * @return The wrapped `HTMLHeadElement`.
+   */
+  get dom(): HTMLHeadElement;
+  /**
+   * Sets or updates the document's `<title>` element inside the `<head>`.
+   * Ensures only one `<title>` exists — updates if found, creates if missing.
+   *
+   * @param text - The title text to apply.
+   * @return This instance for chaining.
+   */
+  title(text: string): this;
+  /**
+   * Sets or updates the `<meta charset="...">` tag in the `<head>`.
+   * Ensures only one charset declaration exists — updates if found, creates if missing.
+   *
+   * @param encoding - The character encoding to set (e.g. "UTF-8").
+   * @return This instance for chaining.
+   */
+  charset(encoding: string): this;
+  /**
+   * Sets or updates the `<meta name="viewport">` tag in the `<head>`.
+   * Ensures only one viewport declaration exists — updates if found, creates if missing.
+   *
+   * @param content - The viewport configuration string (e.g. "width=device-width, initial-scale=1").
+   * @return This instance for chaining.
+   */
+  viewport(content: string): this;
+  /**
+   * Sets or updates a `<meta http-equiv="...">` tag in the `<head>`.
+   * Ensures only one tag per `http-equiv` value exists — updates if found, creates if missing.
+   *
+   * Common use cases include:
+   * - `"refresh"` → auto-refresh or redirect
+   * - `"content-type"` → MIME type and charset
+   * - `"X-UA-Compatible"` → browser compatibility mode
+   *
+   * @param httpEquiv - The `http-equiv` directive (e.g. "refresh", "content-type").
+   * @param content - The `content` value to apply.
+   * @return This instance for chaining.
+   */
+  httpEquiv(httpEquiv: string, content: string): this;
+  /**
+   * Sets or updates the `<meta http-equiv="Content-Security-Policy">` tag in the `<head>`.
+   * Accepts a structured object to declaratively build the CSP string.
+   *
+   * @param policy - An object mapping CSP directives to space-separated values.
+   * @return This instance for chaining.
+   *
+   * @example
+   * head.csp({
+   *   "default-src": "'self'",
+   *   "script-src": "'self' https://cdn.example.com",
+   *   "style-src": "'self' 'unsafe-inline'",
+   *   "frame-src": "https://trusted.com"
+   * });
+   */
+  csp(policy: ContentSecurityPolicy): this;
+  /**
+   * Sets or updates the `<meta name="description">` tag in the `<head>`.
+   * Ensures only one description tag exists — updates if found, creates if missing.
+   *
+   * Commonly used for SEO and social previews.
+   *
+   * @param text - The description content to apply.
+   * @return This instance for chaining.
+   */
+  description(text: string): this;
+  /**
+   * Sets or updates the `<meta name="keywords">` tag in the `<head>`.
+   * Ensures only one keywords tag exists — updates if found, creates if missing.
+   *
+   * Keywords help search engines understand page relevance, though modern SEO relies more on content and structure.
+   *
+   * @param text - A comma-separated list of keywords.
+   * @return This instance for chaining.
+   */
+  keywords(text: string): this;
+  /**
+   * Sets or updates a `<link>` tag in the `<head>` by `rel`.
+   * Ensures only one `<link rel="...">` exists — updates if found, creates if missing.
+   *
+   * Common use cases include:
+   * - `"stylesheet"` → external CSS
+   * - `"icon"` → favicon
+   * - `"manifest"` → web app manifest
+   *
+   * @param rel - The `rel` attribute (e.g. "stylesheet", "icon").
+   * @param href - The `href` value to apply (URL or path to the resource).
+   * @param attributes - Optional additional attributes (e.g. type, media, sizes).
+   * @return This instance for chaining.
+   */
+  link(rel: string, href: string, attributes?: Record<string, string>): this;
+}
+/**
+ * Creates a `DomHead` wrapper for the `<head>` element.
+ * Defaults to the main document, but accepts an optional `HTMLHeadElement`.
+ *
+ * @param head - Optional `<head>` element to wrap (defaults to `document.head`).
+ * @return A `DomHead` instance for fluent head manipulation.
+ */
+declare function $head(head?: HTMLHeadElement): DomHead;
+//#endregion
+//#region src/DomDocument.d.ts
+/**
+ * Wrapper for the global `document` object with typed event listener utilities.
+ * Useful for managing document-level events like visibility changes, selection, or clipboard interactions.
+ */
+declare class DomDocument {
+  constructor(document?: Document);
+  protected _document: Document;
+  /**
+   * Returns the underlying `Document` instance wrapped by this `DomDocument`.
+   * Useful for direct DOM access or interoperability with native APIs.
+   *
+   * @return The wrapped `Document` instance.
+   */
+  get dom(): Document;
+  /**
+   * Returns a `DomBody` wrapper for the document's `<body>` element.
+   * Enables fluent DOM composition and styling for the document body.
+   *
+   * @return A `DomBody` instance wrapping the document's body.
+   */
+  getBody(): DomBody;
+  /**
+   * Returns a `DomHead` wrapper for the document's `<head>` element.
+   * Enables fluent DOM composition and styling for the document head.
+   *
+   * @return A `DomHead` instance wrapping the document's head.
+   */
+  getHead(): DomHead;
+  /**
+   * Adds an event listener to the document.
+   * @param type - The event type (e.g., "visibilitychange", "copy", "selectionchange").
+   * @param handler - The event handler function.
+   * @param options - Optional event listener options.
+   * @return This instance for chaining.
    */
   on<T extends keyof DocumentEventMap>(type: T, handler: (ev: DocumentEventMap[T] & {
     currentTarget: Document;
@@ -1925,6 +2402,16 @@ declare class DomDocument {
    * @return This instance for chaining.
    */
   dispatch(event: Event): this;
+  /**
+   * Queries the document for a single matching element and wraps it in a `DomElement`.
+   * Returns `null` if no match is found.
+   *
+   * This enables fluent DOM manipulation with ergonomic chaining and type safety.
+   *
+   * @param selector - A valid CSS selector string.
+   * @return A `DomElement` wrapper for the matched element, or `null` if not found.
+   */
+  query<T extends keyof DomElementTagNameMap>(selector: string): DomElement<T> | null;
 }
 /**
  * Creates a new DomDocument instance bound to the global `document` object.
@@ -1938,13 +2425,23 @@ declare function $document(): DomDocument;
 //#endregion
 //#region src/DomWindow.d.ts
 /**
- * Wrapper for the global `window` object with typed event listener utilities.
+ * Wrapper for a `Window` object with typed event listener utilities.
  * Useful for managing global events like resize, scroll, or keyboard shortcuts.
  */
 declare class DomWindow {
+  constructor(win?: Window);
+  protected _window: Window;
+  /**
+   * Returns the wrapped `Window` instance.
+   */
+  get dom(): Window;
+  /**
+   * Returns the associated `DomDocument` for this window.
+   */
+  getDocument(): DomDocument;
   /**
    * Adds an event listener to the window.
-   * @param type - The event type (e.g., "click", "input", "mouseenter").
+   * @param type - The event type (e.g., "resize", "scroll", "keydown").
    * @param handler - The event handler function.
    * @param options - Optional event listener options.
    * @return This instance for chaining.
@@ -1957,37 +2454,228 @@ declare class DomWindow {
    * @param type - The event type to remove.
    * @param handler - The original handler function.
    * @param options - Optional event listener options.
-   * @return This DomElement instance for chaining.
+   * @return This instance for chaining.
    */
   off<T extends keyof WindowEventMap>(type: T, handler: (ev: WindowEventMap[T]) => void, options?: boolean | EventListenerOptions): this;
   /**
    * Dispatches a DOM event on the window object.
    *
-   * @param event - The corresponding event instance (e.g., `new Event("resize")`, `new KeyboardEvent("keydown")`).
+   * @param event - The corresponding event instance (e.g., `new Event("resize")`).
    * @return This instance for chaining.
    */
   dispatch(event: Event): this;
+  /**
+   * Sends a message to the wrapped `Window` using `postMessage`.
+   * Useful for communicating with same-origin or cross-origin windows that are listening for messages.
+   *
+   * ⚠️ Ensure the target window is ready to receive messages.
+   * ⚠️ For cross-origin messaging, the receiver must explicitly validate origins.
+   *
+   * @param data - The message payload to send (any serializable object).
+   * @param targetOrigin - The expected origin of the receiver (e.g. "https://example.com" or "*").
+   * @return This instance for chaining.
+   */
+  postMessage(data: any, targetOrigin: string): this;
 }
 /**
- * Creates a new DomWindow instance bound to the global `window` object.
- * Provides typed event listener utilities and fluent dispatching for built-in DOM events.
+ * Creates a `DomWindow` instance bound to the specified `Window` object.
+ * Defaults to the global `window`, but can wrap any window (e.g., iframe's `contentWindow`).
  *
  * Useful for managing global interactions like resize, scroll, keyboard shortcuts, or visibility changes.
  *
- * @return A DomWindow instance wrapping the global `window`.
+ * @param win - Optional `Window` instance to wrap (defaults to global `window`).
+ * @return A `DomWindow` instance wrapping the given window.
  */
-declare function $window(): DomWindow;
+declare function $window(win?: Window): DomWindow;
 //#endregion
 //#region src/IFrame.d.ts
+/**
+ * Fluent wrapper for the `<iframe>` element, extending `DomElement<"iframe">` with iframe-specific APIs.
+ * Inherits styling and DOM manipulation capabilities from `BaseStyle → BaseDom → DomElement`.
+ *
+ * Provides ergonomic methods for setting `src`, sizing, fullscreen permissions, and reloading.
+ * Designed for declarative composition, chaining, and integration with dynamic layout systems.
+ *
+ * Example:
+ * ```ts
+ * $iframe()
+ *   .src("https://example.com")
+ *   .width(800)
+ *   .height(600)
+ *   .allowFullscreen();
+ * ```
+ *
+ * TODO:
+ * - Add `.postMessage()` for messaging into iframe content
+ * - Add `.getContentWindow()` for direct access to iframe's `contentWindow`
+ */
 declare class IFrame extends DomElement<"iframe"> {
   constructor();
+  /**
+   * Returns a `DomWindow` wrapper for the iframe's `contentWindow`.
+   * Enables typed event handling and DOM access within the iframe's window context.
+   *
+   * ⚠️ Cross-origin iframes will restrict access to most properties for security reasons.
+   *
+   * @return A `DomWindow` instance wrapping the iframe's window, or `null` if inaccessible.
+   */
+  getContentWindow(): DomWindow | null;
+  /**
+   * Returns a `DomDocument` wrapper for the iframe's `contentDocument`.
+   * This enables typed event handling and DOM utilities inside the iframe.
+   *
+   * ⚠️ Returns `null` if the iframe is cross-origin or not yet loaded.
+   *
+   * @return A `DomDocument` instance wrapping the iframe's document, or `null` if inaccessible.
+   */
+  getContentDocument(): DomDocument | null;
+  /**
+   * Returns a `DomBody` wrapper for the iframe's inner `<body>` element.
+   * Only works for same-origin iframes. Returns `null` if the iframe is cross-origin,
+   * not yet loaded, or has no accessible body element.
+   *
+   * This enables fluent DOM composition and styling inside the iframe when available.
+   *
+   * @return A `DomBody` instance wrapping the iframe's body, or `null` if inaccessible.
+   */
+  getBody(): DomBody | null;
+  /**
+   * Returns a `DomHead` wrapper for the iframe's inner `<head>` element.
+   * Only works for same-origin iframes. Returns `null` if the iframe is cross-origin or inaccessible.
+   *
+   * @return A `DomHead` instance wrapping the iframe's head, or `null` if inaccessible.
+   */
+  getHead(): DomHead | null;
+  /**
+   * Checks whether the iframe is same-origin with the parent document.
+   * Attempts to access `contentWindow.location.href` and catches any security error.
+   *
+   * @return `true` if same-origin, `false` if cross-origin or inaccessible.
+   */
+  isSameOrigin(): boolean;
+  /**
+   * Sets the `src` attribute of the `<iframe>` element.
+   * Defines the URL to load inside the iframe. Can be same-origin or cross-origin.
+   * This triggers a navigation and replaces the iframe's current content.
+   *
+   * @param value - The URL to load in the iframe.
+   * @return This instance for chaining.
+   */
   src(value: string): this;
+  /**
+   * Enables or disables the `allowFullscreen` capability on the `<iframe>`.
+   * When `true`, allows the iframe content to request fullscreen mode via the Fullscreen API.
+   *
+   * @param value - Whether to allow fullscreen requests (default is `true`).
+   * @return This instance for chaining.
+   */
   allowFullscreen(value?: boolean): this;
+  /**
+   * Sets the `width` attribute of the `<iframe>` element.
+   * Accepts a numeric value in pixels and applies it via the `width` DOM property.
+   * Uses `getStyleValue("width", value)` to normalize units or apply custom logic.
+   *
+   * @param value - The desired width in pixels.
+   * @return This instance for chaining.
+   */
   width(value: number): this;
+  /**
+   * Sets the `height` attribute of the `<iframe>` element.
+   * Accepts a numeric value in pixels and applies it via the `height` DOM property.
+   * Uses `getStyleValue("height", value)` to normalize units or apply custom logic.
+   *
+   * @param value - The desired height in pixels.
+   * @return This instance for chaining.
+   */
   height(value: number): this;
-  setSize(width: number, height: number): this;
-  reload(): void;
+  /**
+   * Sets both the `width` and `height` attributes of the `<iframe>` element.
+   * Delegates to `.width()` and `.height()` internally for unit normalization and chaining.
+   * Useful for concise, declarative sizing of the iframe in pixels.
+   *
+   * @param width - The desired width in pixels.
+   * @param height - The desired height in pixels.
+   * @return This instance for chaining.
+   */
+  size(width: number, height: number): this;
+  /**
+   * Sets or removes the `sandbox` attribute to restrict iframe capabilities.
+   * Accepts an array of sandbox flags (typed) or `undefined` to remove the attribute.
+   *
+   * @param flags - Array of allowed sandbox flags, or `undefined` to remove the attribute.
+   * @return This instance for chaining.
+   */
+  sandbox(flags: IFrameSandboxFlag[] | undefined): this;
+  /**
+   * Sets the `referrerPolicy` attribute to control referrer behavior for iframe requests.
+   * Accepts values like "no-referrer", "origin", "strict-origin", etc.
+   *
+   * @param value - The referrer policy to apply.
+   * @return This instance for chaining.
+   */
+  referrerPolicy(value: ReferrerPolicy): this;
+  /**
+   * Sets the `loading` attribute to control iframe loading behavior.
+   * Use `"lazy"` to defer loading until the iframe is near the viewport.
+   *
+   * @param value - `"lazy"` or `"eager"`.
+   * @return This instance for chaining.
+   */
+  loading(value: "lazy" | "eager"): this;
+  /**
+   * Reloads the iframe by reassigning its `src` attribute.
+   * Works even for cross-origin iframes, as long as `src` is set.
+   * This is the most broadly compatible reload strategy.
+   * @return This instance for chaining.
+   */
+  reloadViaSrc(): this;
+  /**
+   * Reloads the iframe using its `contentWindow.location.reload()` method.
+   * Only works for same-origin iframes. Throws a security error if cross-origin.
+   * @return This instance for chaining.
+   */
+  reloadViaLocation(): this;
+  /**
+   * Reloads the iframe using the most appropriate strategy:
+   *
+   * - Attempts `contentWindow.location.reload()` for same-origin iframes, which preserves dynamic state and scroll position.
+   * - Falls back to reassigning `src` for cross-origin iframes or when `contentWindow` is inaccessible.
+   *
+   * This ensures robust behavior across both same-origin and cross-origin scenarios.
+   *
+   * @return This instance for chaining.
+   */
+  reload(): this;
+  /**
+   * Queries the iframe's `contentDocument` for a matching element and wraps it in a `DomElement`.
+   * Only works for same-origin iframes. Returns `null` if the iframe is cross-origin, inaccessible, or the element is not found.
+   *
+   * This enables safe DOM querying inside iframes with fluent manipulation.
+   *
+   * @param selector - CSS selector to query inside the iframe.
+   * @return A `DomElement` wrapping the matched element, or `null` if not found or inaccessible.
+   */
+  queryInside<T extends keyof DomElementTagNameMap>(selector: string): DomElement<T> | null;
+  /**
+   * Sends a message to the iframe's `contentWindow` using `postMessage`.
+   * Only works for same-origin iframes or cross-origin targets that accept messages.
+   *
+   * ⚠️ Ensure the iframe is loaded and the target window is ready to receive messages.
+   * ⚠️ For cross-origin messaging, the receiver must explicitly validate origins.
+   *
+   * @param data - The message payload to send (any serializable object).
+   * @param targetOrigin - The expected origin of the receiver (e.g. "https://example.com" or "*").
+   * @return This instance for chaining.
+   */
+  postMessage(data: any, targetOrigin: string): this;
 }
+/**
+ * Creates a new `IFrame` instance with a wrapped `<iframe>` element.
+ * This provides access to the fluent iframe API, including sizing, messaging, reload strategies,
+ * and DOM interaction helpers for same-origin content.
+ *
+ * @return A new `IFrame` instance.
+ */
 declare function $iframe(): IFrame;
 //#endregion
 //#region src/ImageElement.d.ts
@@ -2093,6 +2781,367 @@ declare class OptionElement extends DomElement<"option"> {
 }
 declare function $option(): OptionElement;
 //#endregion
+//#region src/PathData.d.ts
+/**
+ * Fluent builder for constructing the `d` attribute of an SVG `<path>` element.
+ * Supports common path commands with type-safe chaining and automatic formatting.
+ *
+ * Example:
+ *   new PathData()
+ *     .moveTo(10, 10)
+ *     .lineTo(100, 100)
+ *     .close()
+ *     .toString(); // "M10 10 L100 100 Z"
+ */
+declare class PathData {
+  protected _segments: string[];
+  /**
+   * Moves the current drawing position to the absolute coordinate (x, y).
+   * Starts a new subpath without drawing a line.
+   *
+   * Equivalent to the SVG `M` command.
+   *
+   * @param x - Absolute x coordinate.
+   * @param y - Absolute y coordinate.
+   * @return This instance for chaining.
+   */
+  moveTo(x: number, y: number): this;
+  /**
+   * Moves the current drawing position by a relative offset (dx, dy).
+   * Starts a new subpath without drawing a line.
+   *
+   * Equivalent to the SVG `m` command.
+   *
+   * @param dx - Relative x offset from the current position.
+   * @param dy - Relative y offset from the current position.
+   * @return This instance for chaining.
+   */
+  moveToRel(dx: number, dy: number): this;
+  /**
+   * Draws a straight line from the current position to the absolute coordinate (x, y).
+   * Adds a visible segment to the path.
+   *
+   * Equivalent to the SVG `L` command.
+   *
+   * @param x - Absolute x coordinate of the line endpoint.
+   * @param y - Absolute y coordinate of the line endpoint.
+   * @return This instance for chaining.
+   */
+  lineTo(x: number, y: number): this;
+  /**
+   * Draws a straight line from the current position by a relative offset (dx, dy).
+   * Adds a visible segment to the path.
+   *
+   * Equivalent to the SVG `l` command.
+   *
+   * @param dx - Relative x offset from the current position.
+   * @param dy - Relative y offset from the current position.
+   * @return This instance for chaining.
+   */
+  lineToRel(dx: number, dy: number): this;
+  /**
+   * Draws a horizontal line from the current position to the absolute x coordinate.
+   * Keeps the current y position unchanged.
+   *
+   * Equivalent to the SVG `H` command.
+   *
+   * @param x - Absolute x coordinate of the line endpoint.
+   * @return This instance for chaining.
+   */
+  horizontal(x: number): this;
+  /**
+   * Draws a horizontal line from the current position by a relative x offset.
+   * Keeps the current y position unchanged.
+   *
+   * Equivalent to the SVG `h` command.
+   *
+   * @param dx - Relative x offset from the current position.
+   * @return This instance for chaining.
+   */
+  horizontalRel(dx: number): this;
+  /**
+   * Draws a vertical line from the current position to the absolute y coordinate.
+   * Keeps the current x position unchanged.
+   *
+   * Equivalent to the SVG `V` command.
+   *
+   * @param y - Absolute y coordinate of the line endpoint.
+   * @return This instance for chaining.
+   */
+  vertical(y: number): this;
+  /**
+   * Draws a vertical line from the current position by a relative y offset.
+   * Keeps the current x position unchanged.
+   *
+   * Equivalent to the SVG `v` command.
+   *
+   * @param dy - Relative y offset from the current position.
+   * @return This instance for chaining.
+   */
+  verticalRel(dy: number): this;
+  /**
+   * Draws a cubic Bézier curve from the current position to the absolute coordinate (x, y),
+   * using two control points to shape the curve.
+   *
+   * Equivalent to the SVG `C` command.
+   *
+   * @param cx1 - Absolute x coordinate of the first control point.
+   * @param cy1 - Absolute y coordinate of the first control point.
+   * @param cx2 - Absolute x coordinate of the second control point.
+   * @param cy2 - Absolute y coordinate of the second control point.
+   * @param x - Absolute x coordinate of the curve endpoint.
+   * @param y - Absolute y coordinate of the curve endpoint.
+   * @return This instance for chaining.
+   */
+  curveTo(cx1: number, cy1: number, cx2: number, cy2: number, x: number, y: number): this;
+  /**
+   * Draws a cubic Bézier curve from the current position by a relative offset (dx, dy),
+   * using two relative control points to shape the curve.
+   *
+   * Equivalent to the SVG `c` command.
+   *
+   * @param dc1x - Relative x offset of the first control point.
+   * @param dc1y - Relative y offset of the first control point.
+   * @param dc2x - Relative x offset of the second control point.
+   * @param dc2y - Relative y offset of the second control point.
+   * @param dx - Relative x offset of the curve endpoint.
+   * @param dy - Relative y offset of the curve endpoint.
+   * @return This instance for chaining.
+   */
+  curveToRel(dc1x: number, dc1y: number, dc2x: number, dc2y: number, dx: number, dy: number): this;
+  /**
+   * Draws a quadratic Bézier curve from the current position to the absolute coordinate (x, y),
+   * using a single control point to shape the curve.
+   *
+   * Equivalent to the SVG `Q` command.
+   *
+   * @param cx - Absolute x coordinate of the control point.
+   * @param cy - Absolute y coordinate of the control point.
+   * @param x - Absolute x coordinate of the curve endpoint.
+   * @param y - Absolute y coordinate of the curve endpoint.
+   * @return This instance for chaining.
+   */
+  quadraticTo(cx: number, cy: number, x: number, y: number): this;
+  /**
+   * Draws a quadratic Bézier curve from the current position by a relative offset (dx, dy),
+   * using a single relative control point to shape the curve.
+   *
+   * Equivalent to the SVG `q` command.
+   *
+   * @param dcx - Relative x offset of the control point.
+   * @param dcy - Relative y offset of the control point.
+   * @param dx - Relative x offset of the curve endpoint.
+   * @param dy - Relative y offset of the curve endpoint.
+   * @return This instance for chaining.
+   */
+  quadraticToRel(dcx: number, dcy: number, dx: number, dy: number): this;
+  /**
+   * Draws an elliptical arc from the current position to the absolute coordinate (x, y),
+   * using the specified radii, rotation, and arc/sweep flags.
+   *
+   * Equivalent to the SVG `A` command.
+   *
+   * @param rx - Horizontal radius of the ellipse.
+   * @param ry - Vertical radius of the ellipse.
+   * @param xAxisRotation - Rotation (in degrees) of the ellipse's x-axis relative to the coordinate system.
+   * @param largeArc - If true, draws the larger of the two possible arcs (sweep angle ≥ 180°).
+   * @param sweep - If true, draws the arc in a "positive-angle" (clockwise) direction.
+   * @param x - Absolute x coordinate of the arc endpoint.
+   * @param y - Absolute y coordinate of the arc endpoint.
+   * @return This instance for chaining.
+   */
+  arcTo(rx: number, ry: number, xAxisRotation: number, largeArc: boolean, sweep: boolean, x: number, y: number): this;
+  /**
+   * Draws an elliptical arc from the current position by a relative offset (dx, dy),
+   * using the specified radii, rotation, and arc/sweep flags.
+   *
+   * Equivalent to the SVG `a` command.
+   *
+   * @param rx - Horizontal radius of the ellipse.
+   * @param ry - Vertical radius of the ellipse.
+   * @param xAxisRotation - Rotation (in degrees) of the ellipse's x-axis relative to the coordinate system.
+   * @param largeArc - If true, draws the larger of the two possible arcs (sweep angle ≥ 180°).
+   * @param sweep - If true, draws the arc in a "positive-angle" (clockwise) direction.
+   * @param dx - Relative x offset of the arc endpoint.
+   * @param dy - Relative y offset of the arc endpoint.
+   * @return This instance for chaining.
+   */
+  arcToRel(rx: number, ry: number, xAxisRotation: number, largeArc: boolean, sweep: boolean, dx: number, dy: number): this;
+  /**
+   * Closes the current subpath by drawing a straight line back to its starting point.
+   * Ensures the shape is fully enclosed, which is important for fill operations.
+   *
+   * Equivalent to the SVG `Z` command.
+   *
+   * @return This instance for chaining.
+   */
+  close(): this;
+  /**
+   * Adds a rectangular path starting at (x, y) with the given width and height.
+   * Uses `moveTo`, `horizontal`, `vertical`, and `close` for fluent composition.
+   *
+   * @param x - Top-left x coordinate.
+   * @param y - Top-left y coordinate.
+   * @param width - Width of the rectangle.
+   * @param height - Height of the rectangle.
+   * @return This instance for chaining.
+   */
+  rect(x: number, y: number, width: number, height: number): this;
+  /**
+   * Adds a rectangular path using relative coordinates from the current position.
+   * Uses `moveToRel`, `horizontalRel`, `verticalRel`, and `close` for fluent composition.
+   *
+   * @param dx - Relative x offset from the current position.
+   * @param dy - Relative y offset from the current position.
+   * @param width - Width of the rectangle.
+   * @param height - Height of the rectangle.
+   * @return This instance for chaining.
+   */
+  rectRel(dx: number, dy: number, width: number, height: number): this;
+  /**
+   * Adds a rounded rectangle path starting at (x, y) with the given width, height, and corner radius.
+   * Uses `moveTo`, `arcTo`, `horizontal`, `vertical`, and `close` for fluent composition.
+   *
+   * @param x - Top-left x coordinate.
+   * @param y - Top-left y coordinate.
+   * @param width - Width of the rectangle.
+   * @param height - Height of the rectangle.
+   * @param r - Radius of the corners.
+   * @return This instance for chaining.
+   */
+  roundedRect(x: number, y: number, width: number, height: number, r: number): this;
+  /**
+   * Adds a circular path centered at (cx, cy) with radius `r`.
+   * Uses `moveTo` and two `arcTo` commands to complete the full circle.
+   *
+   * This creates a clockwise circle starting at the rightmost point.
+   *
+   * @param cx - Center x coordinate.
+   * @param cy - Center y coordinate.
+   * @param r - Radius of the circle.
+   * @return This instance for chaining.
+   */
+  circle(cx: number, cy: number, r: number): this;
+  /**
+   * Adds a circular path using relative coordinates from the current position.
+   * Uses `moveToRel` and two `arcToRel` commands to complete the full circle.
+   *
+   * Starts at (r, 0) relative to the current position.
+   *
+   * @param dx - Relative x offset to the circle center.
+   * @param dy - Relative y offset to the circle center.
+   * @param r - Radius of the circle.
+   * @return This instance for chaining.
+   */
+  circleRel(dx: number, dy: number, r: number): this;
+  /**
+   * Adds an elliptical path centered at (cx, cy) with radii `rx` and `ry`.
+   * Uses `moveTo` and two `arcTo` commands to complete the full ellipse.
+   *
+   * Starts at the rightmost point of the ellipse and draws two arcs to complete it.
+   *
+   * @param cx - Center x coordinate.
+   * @param cy - Center y coordinate.
+   * @param rx - Horizontal radius.
+   * @param ry - Vertical radius.
+   * @return This instance for chaining.
+   */
+  ellipse(cx: number, cy: number, rx: number, ry: number): this;
+  /**
+   * Adds a regular star shape centered at (cx, cy) with the given number of points and outer radius.
+   * Uses `moveTo` and `lineTo` to connect alternating outer and inner vertices.
+   *
+   * @param cx - Center x coordinate.
+   * @param cy - Center y coordinate.
+   * @param points - Number of star points (minimum 2).
+   * @param radius - Outer radius of the star.
+   * @param insetRatio - Ratio of inner radius to outer radius (default: 0.5).
+   * @return This instance for chaining.
+   */
+  star(cx: number, cy: number, points: number, radius: number, insetRatio?: number): this;
+  /**
+   * Adds a closed polygon path using the provided list of points.
+   * Uses `moveTo` and `lineTo` to connect each vertex, then closes the shape.
+   *
+   * @param points - Array of [x, y] coordinate pairs.
+   * @return This instance for chaining.
+   */
+  polygon(points: [number, number][]): this;
+  /**
+   * Adds an open polyline path using the provided list of points.
+   * Uses `moveTo` and `lineTo` to connect each vertex without closing the shape.
+   *
+   * @param points - Array of [x, y] coordinate pairs.
+   * @return This instance for chaining.
+   */
+  polyline(points: [number, number][]): this;
+  /**
+   * Adds a smooth spline through the given points using cubic Bézier segments.
+   * Uses Catmull-Rom to Bézier conversion for natural curvature.
+   *
+   * @param points - Array of [x, y] coordinate pairs (minimum 2).
+   * @param tension - Controls curve tightness (default: 0.5). Lower = looser, higher = tighter.
+   * @return This instance for chaining.
+   */
+  spline(points: [number, number][], tension?: number): this;
+  /**
+   * Adds a path from the given list of points.
+   * Uses `moveTo` and `lineTo` to connect each vertex, optionally closing the shape.
+   *
+   * @param points - Array of [x, y] coordinate pairs.
+   * @param close - Whether to close the path (default: false).
+   * @return This instance for chaining.
+   */
+  pathFrom(points: [number, number][], close?: boolean): this;
+  /**
+   * Adds a path using relative point offsets from the current position.
+   * Uses `moveToRel` and `lineToRel` to connect each vertex, optionally closing the shape.
+   *
+   * @param deltas - Array of [dx, dy] relative coordinate pairs.
+   * @param close - Whether to close the path (default: false).
+   * @return This instance for chaining.
+   */
+  pathFromRel(deltas: [number, number][], close?: boolean): this;
+  /**
+   * Adds a sequence of cubic Bézier segments using explicit control and end points.
+   * Each segment is defined by two control points and one endpoint.
+   *
+   * The first point is used as the starting position (via `moveTo`),
+   * and each subsequent triplet defines a `curveTo` segment.
+   *
+   * @param points - Array of [x, y] coordinate pairs: [start, c1, c2, end, c1, c2, end, ...].
+   *                 Must contain 1 + 3×N points (N ≥ 1).
+   * @return This instance for chaining.
+   */
+  polyBezier(points: [number, number][]): this;
+  /**
+   * Adds a sequence of quadratic Bézier segments using explicit control and end points.
+   * Each segment is defined by one control point and one endpoint.
+   *
+   * The first point is used as the starting position (via `moveTo`),
+   * and each subsequent pair defines a `quadraticTo` segment.
+   *
+   * @param points - Array of [x, y] coordinate pairs: [start, c1, end, c1, end, ...].
+   *                 Must contain 1 + 2×N points (N ≥ 1).
+   * @return This instance for chaining.
+   */
+  polyQuadratic(points: [number, number][]): this;
+  /**
+   * Adds a sequence of elliptical arc segments.
+   * Each segment is defined by radii, rotation, arc/sweep flags, and an endpoint.
+   *
+   * The first point is used as the starting position (via `moveTo`),
+   * and each subsequent arc segment is defined by a tuple of:
+   * [rx, ry, xAxisRotation, largeArc, sweep, x, y]
+   *
+   * @param segments - Array of arc segments: [start, arc1, arc2, ...].
+   *                   Must contain 1 + N×7 points (N ≥ 1).
+   * @return This instance for chaining.
+   */
+  polyArc(segments: (number | boolean)[][]): this;
+  toString(): string;
+}
+//#endregion
 //#region src/ProgressElement.d.ts
 /**
  * A typed wrapper around the native <progress> HTML element, extending the DomElement base class.
@@ -2143,9 +3192,273 @@ declare class SelectElement extends DomElement<"select"> {
 }
 declare function $select(): SelectElement;
 //#endregion
+//#region src/SvgCircle.d.ts
+/**
+ * Wrapper for the `<circle>` SVG element, extending `BaseSvgElement<"circle">` with circle-specific functionality.
+ *
+ * Provides a fluent API for setting circle geometry via `cx`, `cy`, and `r` attributes.
+ * Inherits common styling and transform methods from `BaseSvgElement`, enabling consistent manipulation across SVG shape elements.
+ *
+ * Ideal for constructing circular shapes, markers, and radial primitives with ergonomic chaining.
+ */
+declare class SvgCircle extends BaseSvgElement<"circle"> {
+  constructor();
+  /**
+   * Sets the `cx` (center x) coordinate.
+   * @param cx - Horizontal center position.
+   * @return This instance for chaining.
+   */
+  cx(cx: number): this;
+  /**
+   * Sets the `cy` (center y) coordinate.
+   * @param cy - Vertical center position.
+   * @return This instance for chaining.
+   */
+  cy(cy: number): this;
+  /**
+   * Sets the `r` (radius) of the circle.
+   * @param r - Radius in user units.
+   * @return This instance for chaining.
+   */
+  r(r: number): this;
+}
+/**
+ * Creates a new SvgCircle element.
+ *
+ * @return A new SvgCircle instance.
+ */
+declare function $circle(): SvgCircle;
+//#endregion
+//#region src/SvgElement.d.ts
+/**
+ * Wrapper for the `<svg>` root element, extending `BaseSvgElement<"svg">` with viewport and layout configuration.
+ *
+ * Provides a fluent API for setting width, height, viewBox, and namespace attributes.
+ * Inherits common styling and transform methods from `BaseSvgElement`, enabling consistent manipulation across the entire SVG tree.
+ *
+ * Ideal for constructing standalone SVG documents or embedding scalable vector graphics in UI components.
+ */
+declare class SvgElement extends BaseSvgElement<"svg"> {
+  constructor();
+  /**
+   * Sets the `width` of the SVG viewport.
+   * @param w - Width in pixels or units.
+   * @return This instance for chaining.
+   */
+  width(w: number | string): this;
+  /**
+   * Sets the `height` of the SVG viewport.
+   * @param h - Height in pixels or units.
+   * @return This instance for chaining.
+   */
+  height(h: number | string): this;
+  /**
+   * Sets the `viewBox` attribute for scalable layout.
+   * @param x - Minimum x coordinate.
+   * @param y - Minimum y coordinate.
+   * @param w - ViewBox width.
+   * @param h - ViewBox height.
+   * @return This instance for chaining.
+   */
+  viewBox(x: number, y: number, w: number, h: number): this;
+}
+/**
+ * Creates a new SvgElement root.
+ *
+ * @return A new SvgElement instance.
+ */
+declare function $svg(): SvgElement;
+//#endregion
+//#region src/SvgGroup.d.ts
+/**
+ * Wrapper for the `<g>` SVG element, extending `BaseSvgElement<"g">` with group-specific functionality.
+ *
+ * Provides a fluent API for grouping multiple SVG elements under a shared transform or style context.
+ * Inherits common styling and transform methods from `BaseSvgElement`, enabling consistent manipulation across grouped shapes.
+ *
+ * Ideal for structuring reusable components, applying collective transforms, or organizing layered SVG content.
+ */
+declare class SvgGroup extends BaseSvgElement<"g"> {
+  constructor();
+}
+/**
+ * Creates a new SvgGroup element.
+ *
+ * @return A new SvgGroup instance.
+ */
+declare function $group(): SvgGroup;
+//#endregion
+//#region src/SvgPath.d.ts
+/**
+ * Wrapper for the `<path>` SVG element, extending `BaseSvgElement<"path">` with path-specific functionality.
+ *
+ * Provides a fluent API for setting the `d` attribute using either raw path strings or structured `PathData` builders.
+ * Inherits common styling and transform methods from `BaseSvgElement`, enabling consistent manipulation across SVG shape elements.
+ *
+ * Ideal for constructing complex vector shapes, curves, and outlines with ergonomic chaining.
+ */
+declare class SvgPath extends BaseSvgElement<"path"> {
+  constructor();
+  /**
+   * Sets the `d` attribute using a raw string or PathData instance.
+   * @param path - Path data string or builder.
+   * @return This instance for chaining.
+   */
+  d(path: string | PathData): this;
+}
+/**
+ * Creates a new SvgPath element.
+ *
+ * @return A new SvgPath instance.
+ */
+declare function $path(): SvgPath;
+//#endregion
+//#region src/SvgRect.d.ts
+/**
+ * Wrapper for the `<rect>` SVG element, extending `BaseSvgElement<"rect">` with rect-specific functionality.
+ *
+ * Provides a fluent API for setting rectangle geometry via `x`, `y`, `width`, `height`, and optional corner radii.
+ * Inherits common styling and transform methods from `BaseSvgElement`, enabling consistent manipulation across SVG shape elements.
+ *
+ * Ideal for constructing positioned rectangles, UI blocks, and layout primitives with ergonomic chaining.
+ */
+declare class SvgRect extends BaseSvgElement<"rect"> {
+  constructor();
+  /**
+   * Sets the `x` position of the rectangle.
+   * @param x - Horizontal coordinate.
+   * @return This instance for chaining.
+   */
+  x(x: number): this;
+  /**
+   * Sets the `y` position of the rectangle.
+   * @param y - Vertical coordinate.
+   * @return This instance for chaining.
+   */
+  y(y: number): this;
+  /**
+   * Sets the `width` of the rectangle.
+   * @param w - Width in user units.
+   * @return This instance for chaining.
+   */
+  width(w: number): this;
+  /**
+   * Sets the `height` of the rectangle.
+   * @param h - Height in user units.
+   * @return This instance for chaining.
+   */
+  height(h: number): this;
+  /**
+   * Sets the horizontal corner radius (`rx`).
+   * @param rx - Horizontal radius.
+   * @return This instance for chaining.
+   */
+  rx(rx: number): this;
+  /**
+   * Sets the vertical corner radius (`ry`).
+   * @param ry - Vertical radius.
+   * @return This instance for chaining.
+   */
+  ry(ry: number): this;
+}
+/**
+ * Creates a new SvgRect element.
+ *
+ * @return A new SvgRect instance.
+ */
+declare function $rect(): SvgRect;
+//#endregion
+//#region src/TextArea.d.ts
+/**
+ * Fluent wrapper for the native `<textarea>` element.
+ * Provides ergonomic access to common attributes like `name`, `value`, `placeholder`, `rows`, `cols`, and `wrap`.
+ * Enables type-safe, chainable configuration for form inputs, comment boxes, and multi-line editors.
+ *
+ * This class extends `DomElement<"textarea">`, preserving full DOM access while offering a declarative API.
+ * Ideal for dynamic UI composition, form scaffolding, and reusable component abstractions.
+ */
+declare class TextArea extends DomElement<"textarea"> {
+  constructor();
+  /**
+   * Sets the `name` attribute of the element.
+   * Useful for form serialization and identifying the field in submissions.
+   *
+   * @param value - The name to assign to the element.
+   * @return This instance for chaining.
+   */
+  name(value: string): this;
+  /**
+   * Sets the current value of the element.
+   * Applies to `<input>` and `<textarea>` elements.
+   *
+   * @param value - The string value to assign.
+   * @return This instance for chaining.
+   */
+  value(value: string): this;
+  /**
+   * Retrieves the current value of the element.
+   * Useful for reading user input or programmatic state.
+   *
+   * @return The string value of the element.
+   */
+  getValue(): string;
+  /**
+   * Sets the `placeholder` text shown when the element is empty.
+   * Useful for guiding user input with contextual hints or expected formatting.
+   *
+   * Applies to `<input>` and `<textarea>` elements.
+   *
+   * @param value - The placeholder string to display.
+   * @return This instance for chaining.
+   */
+  placeholder(value: string): this;
+  /**
+   * Sets the number of visible text rows in the `<textarea>`.
+   * Useful for controlling vertical size and layout in forms or editors.
+   *
+   * @param count - The number of rows to display.
+   * @return This instance for chaining.
+   */
+  rows(count: number): this;
+  /**
+   * Sets the number of visible character columns in the `<textarea>`.
+   * Useful for controlling horizontal size and layout in forms or editors.
+   *
+   * @param count - The number of columns to display.
+   * @return This instance for chaining.
+   */
+  cols(count: number): this;
+  /**
+   * Sets the `wrap` behavior for text input in the `<textarea>`.
+   * Controls how text is wrapped when submitted or displayed.
+   *
+   * - `"soft"`: No automatic line breaks; text wraps visually but not in form submission.
+   * - `"hard"`: Text wraps and includes line breaks in submitted value.
+   * - `"off"`: Disables wrapping entirely (non-standard but supported in some browsers).
+   *
+   * @param mode - The desired wrap mode.
+   * @return This instance for chaining.
+   */
+  wrap(mode: TextAreaWrapMode): this;
+  /**
+   * Sets the maximum number of characters allowed in the `<textarea>`.
+   * Useful for input validation, limiting user responses, or enforcing content constraints.
+   *
+   * @param limit - The maximum number of characters allowed.
+   * @return This instance for chaining.
+   */
+  maxLength(limit: number): this;
+}
+/**
+ * Creates a new TextArea element.
+ *
+ * @return A new TextArea instance.
+ */
+declare function $textarea(): TextArea;
+//#endregion
 //#region src/utils.d.ts
 declare function uniqueId(): string;
 declare function camelToKebab(prop: string): string;
 declare function getStyleValue(name: Autocomplete<keyof CssProperties>, value: string | number): string;
 //#endregion
-export { $, $a, $body, $btn, $canvas, $document, $iframe, $img, $input, $option, $progress, $query, $select, $window, AnchorElement, Autocomplete, BaseDom, BaseStyle, Button, Canvas, CssProperties, type CssProperty, CssRule, DomBody, DomDocument, DomElement, DomElementChild, DomElementEventMap, DomElementTagNameMap, DomWindow, IFrame, ImageElement, InputCheckbox, InputColor, InputElementMap, InputNumber, InputRange, InputText, LinearGradientDirection, MediaRule, OptionElement, ProgressElement, SVG_TAGS, SelectElement, StyleSheet, TAG_ALIAS, TagAlias, UNITLESS_CSS_PROPS, VENDOR_CSS_PROPS, camelToKebab, getStyleValue, uniqueId };
+export { $, $a, $body, $btn, $canvas, $circle, $document, $group, $head, $iframe, $img, $input, $option, $path, $progress, $query, $rect, $select, $svg, $textarea, $window, AnchorElement, Autocomplete, BaseDom, BaseStyle, BaseSvgElement, Button, Canvas, ContentSecurityPolicy, CssProperties, type CssProperty, CssRule, DomBody, DomDocument, DomElement, DomElementChild, DomElementEventMap, DomElementTagNameMap, DomHead, DomWindow, IFrame, IFrameSandboxFlag, ImageElement, InputCheckbox, InputColor, InputElementMap, InputNumber, InputRange, InputText, LinearGradientDirection, MediaRule, OptionElement, PathData, ProgressElement, SVG_TAGS, SelectElement, StyleSheet, SvgCircle, SvgElement, SvgElementTagNameMap, SvgGroup, SvgPath, SvgRect, TAG_ALIAS, TagAlias, TextArea, TextAreaWrapMode, UNITLESS_CSS_PROPS, VENDOR_CSS_PROPS, camelToKebab, getStyleValue, uniqueId };