DOM Manipulation

/**
 * Insert element as the last child of parent
 * @param parent - Container element to append to
 * @param element - Element to insert
 */
function append(parent: SugarElement<Node>, element: SugarElement<Node>): void;

/**
 * Insert element as the first child of parent  
 * @param parent - Container element to prepend to
 * @param element - Element to insert
 */
function prepend(parent: SugarElement<Node>, element: SugarElement<Node>): void;

/**
 * Insert element immediately before the marker element
 * @param marker - Reference element for insertion point
 * @param element - Element to insert
 */
function before(marker: SugarElement<Node>, element: SugarElement<Node>): void;

/**
 * Insert element immediately after the marker element
 * @param marker - Reference element for insertion point  
 * @param element - Element to insert
 */
function after(marker: SugarElement<Node>, element: SugarElement<Node>): void;

/**
 * Insert element at specific index within parent's children
 * @param parent - Container element
 * @param element - Element to insert
 * @param index - Zero-based position for insertion
 */
function appendAt(parent: SugarElement<Node>, element: SugarElement<Node>, index: number): void;

/**
 * Wrap an element with a wrapper element
 * @param element - Element to be wrapped
 * @param wrapper - Wrapper element
 */
function wrap(element: SugarElement<Node>, wrapper: SugarElement<Node>): void;

import { SugarElement, Insert } from "@ephox/sugar";

// Create elements
const container = SugarElement.fromTag('div');
const header = SugarElement.fromTag('h1');
const paragraph = SugarElement.fromTag('p');

// Append to container
Insert.append(container, header);
Insert.append(container, paragraph);

// Insert at specific position
const newDiv = SugarElement.fromTag('div');
Insert.appendAt(container, newDiv, 1); // Between header and paragraph

// Wrap existing element
const wrapper = SugarElement.fromTag('section');
Insert.wrap(container, wrapper);

/**
 * Insert multiple elements before the marker element
 * @param marker - Reference element for insertion point
 * @param elements - Array of elements to insert
 */
function before(marker: SugarElement<Node>, elements: SugarElement<Node>[]): void;

/**
 * Insert multiple elements after the marker element
 * @param marker - Reference element for insertion point
 * @param elements - Array of elements to insert
 */
function after(marker: SugarElement<Node>, elements: SugarElement<Node>[]): void;

/**
 * Insert multiple elements as first children of parent
 * @param parent - Container element
 * @param elements - Array of elements to insert
 */
function prepend(parent: SugarElement<Node>, elements: SugarElement<Node>[]): void;

/**
 * Insert multiple elements as last children of parent
 * @param parent - Container element  
 * @param elements - Array of elements to insert
 */
function append(parent: SugarElement<Node>, elements: SugarElement<Node>[]): void;

/**
 * Remove element from its parent, destroying the element
 * @param element - Element to remove
 */
function remove(element: SugarElement<Node>): void;

/**
 * Remove all children from element but keep the element itself
 * @param element - Element to empty
 */
function empty(element: SugarElement<Node>): void;

/**
 * Remove wrapper element but keep its children in place
 * @param wrapper - Wrapper element to remove
 */
function unwrap(wrapper: SugarElement<Node>): void;

import { Remove } from "@ephox/sugar";

// Remove element completely
Remove.remove(oldElement);

// Clear content but keep element
Remove.empty(container);

// Remove wrapper, preserve children
Remove.unwrap(temporaryWrapper);

/**
 * Create shallow copy of element (no children copied)
 * @param original - Element to clone
 * @returns Cloned element without children
 */
function shallow<E extends Node>(original: SugarElement<E>): SugarElement<E>;

/**
 * Create deep copy of element including all children
 * @param original - Element to clone  
 * @returns Cloned element with all descendants
 */
function deep<E extends Node>(original: SugarElement<E>): SugarElement<E>;

/**
 * Create shallow copy with different tag name
 * @param original - Element to clone
 * @param tag - New tag name for the clone
 * @returns Cloned element with new tag, no children
 */
function shallowAs<K extends keyof HTMLElementFullTagNameMap>(
  original: SugarElement<Element>, 
  tag: K
): SugarElement<HTMLElementFullTagNameMap[K]>;

/**
 * Create deep copy with different tag name
 * @param original - Element to clone
 * @param tag - New tag name for the clone
 * @returns Cloned element with new tag and all children
 */
function copy<K extends keyof HTMLElementFullTagNameMap>(
  original: SugarElement<Element>, 
  tag: K
): SugarElement<HTMLElementFullTagNameMap[K]>;

/**
 * Change element's tag name while preserving children
 * @param original - Element to mutate
 * @param tag - New tag name
 * @returns New element with different tag, same children
 */
function mutate<K extends keyof HTMLElementFullTagNameMap>(
  original: SugarElement<Element>, 
  tag: K
): SugarElement<HTMLElementFullTagNameMap[K]>;

/**
 * Test if two elements refer to the same DOM node
 * @param e1 - First element
 * @param e2 - Second element  
 * @returns True if elements are identical
 */
function eq(e1: SugarElement<unknown>, e2: SugarElement<unknown>): boolean;

/**
 * Test if two elements are structurally equal (same content)
 * @param e1 - First element
 * @param e2 - Second element
 * @returns True if elements have same structure and content
 */
function isEqualNode(e1: SugarElement<Node>, e2: SugarElement<Node>): boolean;

/**
 * Test if element is contained within another element
 * @param container - Potential container element
 * @param contained - Element that might be contained
 * @returns True if container contains the element
 */
function contains(container: SugarElement<Node>, contained: SugarElement<Node>): boolean;

/**
 * Test if element is a member of an array of elements
 * @param element - Element to search for
 * @param elements - Array of elements to search in
 * @returns True if element is found in array
 */
function member(element: SugarElement<unknown>, elements: SugarElement<unknown>[]): boolean;

/**
 * Set focus to an element with optional scroll prevention
 * @param element - Element to focus
 * @param preventScroll - Whether to prevent automatic scrolling
 */
function focus(element: SugarElement<HTMLElement>, preventScroll?: boolean): void;

/**
 * Remove focus from an element
 * @param element - Element to blur
 */
function blur(element: SugarElement<HTMLElement>): void;

/**
 * Check if element currently has focus
 * @param element - Element to test
 * @returns True if element has focus
 */
function hasFocus(element: SugarElement<Node>): boolean;

/**
 * Get the currently active (focused) element
 * @param root - Root node to search within
 * @returns Active element if found
 */
function active<T extends HTMLElement>(root?: RootNode): Optional<SugarElement<T>>;

/**
 * Focus element only if no descendant already has focus
 * @param element - Element to conditionally focus
 */
function focusInside(element: SugarElement<HTMLElement>): void;

/**
 * Find focused descendant within element
 * @param element - Element to search within
 * @returns Focused descendant if found
 */
function search(element: SugarElement<Node>): Optional<SugarElement<HTMLElement>>;

/**
 * Test if one position comes after another in document order
 * @param start - Starting element
 * @param soffset - Starting offset
 * @param finish - Ending element  
 * @param foffset - Ending offset
 * @returns True if start position is after finish position
 */
function after(
  start: SugarElement<Node>, 
  soffset: number, 
  finish: SugarElement<Node>, 
  foffset: number
): boolean;

/**
 * Find common ancestor of two positions
 * @param start - Starting element
 * @param soffset - Starting offset
 * @param finish - Ending element
 * @param foffset - Ending offset  
 * @returns Common ancestor element
 */
function commonAncestorContainer(
  start: SugarElement<Node>, 
  soffset: number, 
  finish: SugarElement<Node>, 
  foffset: number
): SugarElement<Node>;

/**
 * Generate array of indices representing path from ancestor to descendant
 * @param ancestor - Starting ancestor element
 * @param descendant - Target descendant element
 * @returns Array of child indices forming path, if valid
 */
function path(ancestor: SugarElement<Node>, descendant: SugarElement<Node>): Optional<number[]>;

/**
 * Follow a path of child indices from ancestor to find descendant
 * @param ancestor - Starting ancestor element
 * @param descendantPath - Array of child indices to follow
 * @returns Found descendant element, if path is valid
 */
function follow(ancestor: SugarElement<Node>, descendantPath: number[]): Optional<SugarElement<Node>>;

/**
 * Get outer HTML of element (handles Shadow DOM)
 * @param element - Element to get HTML from
 * @returns Complete HTML string including element tags
 */
function getOuter(element: SugarElement<Node>): string;

/**
 * Add stylesheet link to document head
 * @param url - URL of stylesheet to load
 * @param scope - Document to add link to (defaults to current document)
 * @returns Created link element
 */
function addStylesheet(url: string, scope?: SugarElement<Document>): SugarElement<HTMLLinkElement>;

/**
 * Get HTML representation of element, with Shadow DOM safety
 * @param element - Element to get HTML from
 * @returns HTML string, or '#shadow-root' for shadow roots
 */
function getHtml(element: SugarElement<Node>): string;

// Re-exported from other modules
type RootNode = SugarElement<Document | ShadowRoot>;