import { ReverseSortedSet } from "./helpers/reverseSortedSet.js";
import type { ReverseSortedSetPointer } from "./helpers/reverseSortedSet.js";

/*
 * QueueRunner
 *
 * `queue()`d runners are executed on the next timer tick, by order of their
 * `prio` values.
 */
interface QueueRunner {
	prio: number; // Higher values have higher priority
	queueRun(): void;

	[ptr: ReverseSortedSetPointer]: QueueRunner;
}

let sortedQueue: ReverseSortedSet<QueueRunner, "prio"> | undefined; // When set, a runQueue is scheduled or currently running.
let runQueueDepth = 0; // Incremented when a queue event causes another queue event to be added. Reset when queue is empty. Throw when >= 42 to break (infinite) recursion.
let freezeCount = 0; // While > 0 (see `freeze()`), `runQueue` is paused and updates accumulate.
let topRedrawScope: Scope | undefined; // The scope that triggered the current redraw. Elements drawn at this scope level may trigger 'create' animations.
// During a teardown (a scope being cleaned), this holds the element that *survives* that teardown:
// the element whose child content is being removed, but which itself stays in the DOM. Value-restoring
// cleaners (attributes/classes/styles/properties/event listeners) only need to run for this element;
// for any element nested below it, the element itself is being removed from the DOM, so reverting its
// attributes would be wasted work. Analogous to how `removeNodes` only detaches the top-level node.
let survivingEl: Element | undefined;

// Side-effects that a scope applied to its *own* element and that must be undone when the scope is
// cleaned (so the element returns to its pre-scope state before a re-render, or stays clean when the
// scope goes away). Rather than allocating a capturing closure per side-effect, each ContentScope
// keeps a single flat `sideEffects` array of (type, key, value) triplets. All entries target the
// scope's own element, so whether they need undoing can be decided once per scope (see `delete`).
const enum SideEffect {
	Class = 0, // key: class name           value: whether the class was present before (boolean)
	Style = 1, // key: camelCase style prop or `--custom-prop`  value: previous style value (string)
	Prop = 2,  // key: DOM property name     value: previous property value
	Attr = 3,  // key: attribute name        value: previous attribute value (string | null)
	Event = 4, // key: event name            value: the listener function to remove
}

function recordSideEffect(scope: ContentScope, type: SideEffect, key: any, value: any) {
	(scope.sideEffects ||= []).push(type, key, value);
}

// Undo the side-effects in reverse (LIFO) order, restoring the element to its pre-scope state.
function undoSideEffects(el: any, se: any[]) {
	for (let i = se.length - 3; i >= 0; i -= 3) {
		const key = se[i + 1];
		const value = se[i + 2];
		switch (se[i] as SideEffect) {
			case SideEffect.Class: value ? el.classList.add(key) : el.classList.remove(key); break;
			case SideEffect.Style:
				if (key[0] === "-" && key[1] === "-") value ? el.style.setProperty(key, value) : el.style.removeProperty(key);
				else el.style[key] = value == null ? "" : value;
				break;
			case SideEffect.Prop: el[key] = value; break;
			case SideEffect.Attr: value == null ? el.removeAttribute(key) : el.setAttribute(key, value); break;
			case SideEffect.Event: el.removeEventListener(key, value); break;
		}
	}
}

/** @internal */
export type TargetType = any[] | { [key: string | symbol]: any } | Map<any, any> | Set<any>;


function queue(runner: QueueRunner) {
	if (!sortedQueue) {
		sortedQueue = new ReverseSortedSet<QueueRunner, "prio">("prio");
		queueMicrotask(runQueue);
	} else if (!(runQueueDepth & 1)) {
		runQueueDepth++; // Make it uneven
		if (runQueueDepth > 98) {
			throw new Error("Too many recursive updates from observes");
		}
	}
	sortedQueue.add(runner);
}

/**
 * Forces the immediate and synchronous execution of all pending reactive updates.
 *
 * Normally, changes to observed data sources (like proxied objects or arrays)
 * are processed asynchronously in a batch after a brief timeout (0ms). This function
 * allows you to bypass the timeout and process the update queue immediately.
 *
 * This can be useful in specific scenarios where you need the DOM to be updated
 * synchronously.
 *
 * This function is re-entrant, meaning it is safe to call `runQueue` from within
 * a function that is itself being executed as part of an update cycle triggered
 * by a previous (or the same) `runQueue` call.
 *
 * @example
 * ```typescript
 * const $data = A.proxy("before");
 *
 * A('#', $data);
 * console.log(1, document.body.innerHTML); // before
 *
 * // Make an update that should cause the DOM to change.
 * $data.value = "after";
 *
 * // Normally, the DOM update would happen after a timeout.
 * // But this causes an immediate update:
 * A.runQueue();
 *
 * console.log(2, document.body.innerHTML); // after
 * ```
 */
export function runQueue(): void {
	if (freezeCount) return; // Paused by `freeze()`; updates stay queued until thawed.
	let time = Date.now();
	// Whoever triggered this flush may be inside a `peek()` — for instance
	// `route.go()`, which runs the queue synchronously. That has nothing to do
	// with the scopes we're about to re-run: if they were to observe `peeking`
	// they would silently register no subscriptions at all and never update
	// again. Suspend it for the duration of the flush.
	const wasPeeking = peeking;
	peeking = 0;
	try {
		while (sortedQueue) {
			const runner = sortedQueue.fetchLast();
			if (!runner) break;
			if (runQueueDepth & 1) runQueueDepth++; // Make it even
			runner.queueRun();
		}
	} finally {
		peeking = wasPeeking;
	}
	sortedQueue = undefined;
	runQueueDepth = 0;
	time = Date.now() - time;
	if (time > 9) console.debug(`Aberdeen queue took ${time}ms`);
}

/**
 * Pause processing of reactive updates until the returned *thaw* function is called.
 *
 * While frozen, changes to observed data still accumulate, but no re-renders run. Freezes
 * stack: if there are multiple outstanding freezes, redraws resume only once the last one is
 * thawed. This is useful to batch an async burst of changes into a single update pass, or to
 * hold the UI steady (e.g. the dev tools use it for "freeze redraws").
 *
 * @returns A function that releases this freeze. Calling it more than once has no effect.
 *
 * @example
 * ```typescript
 * const thaw = A.freeze();
 * // ...make many changes without intermediate redraws...
 * thaw(); // redraws run now (if no other freezes remain)
 * ```
 */
export function freeze(): () => void {
	freezeCount++;
	let released = false;
	return () => {
		if (released) return;
		released = true;
		if (!--freezeCount) runQueue();
	};
}

/**
 * A sort key, as used by {@link onEach}, is a value that determines the order of items. It can
 * be a number, string, or an array of numbers/strings. The sort key is used to sort items
 * based on their values. The sort key can also be `undefined`, which indicates that the item
 * should be ignored.
 * @internal
 */
export type SortKeyType = number | string | Array<number | string> | undefined | void;

/**
 * Given an array of (possibly fractional) numbers or strings, this function returns a string
 * that sorts by natural number ordering.
 */
function arrayToStr(parts: (number | string)[]): string {
	let result = '';
	for (let i = 0; i < parts.length; i++) {
		const part = parts[i];
		if (typeof part === "string") {
			result += `${part}\x01`; // end-of-string
			continue;
		}
		if (!Number.isFinite(part)) {
			throw new Error("onEach() sort key must be a finite number, string or an array of such");
		}
		// Split the number into an integer part and a positive fraction. Rounding *down* makes
		// the fraction positive for negative numbers as well (-2.5 becomes -3 + 0.5), which is
		// what makes the lexicographic ordering below work out for both signs.
		let num = Math.floor(part);
		let frac = part - num;
		const negative = num < 0;
		if (negative) num = -num;
		let digits = "";
		while (num > 0) {
			/*
			* We're reserving a few character codes:
			* 0 - for compatibility
			* 1 - separator between array items
			* 65535 - for compatibility
			*/
			digits = String.fromCharCode(
				negative ? 65534 - (num % 65533) : 2 + (num % 65533),
			) + digits;
			num = Math.floor(num / 65533);
		}
		// Prefix the number of digits, counting down from 128 for negative and up for positive
		result += String.fromCharCode(128 + (negative ? -digits.length : digits.length)) + digits;
		// Fraction digits, base 65533, most significant first. As an omitted digit sorts
		// before any digit character, a whole number sorts before the same number with a
		// fraction. Four digits (64 bits) exceed double precision; the clamp catches the
		// rounding edge where a fraction that approaches 1 would yield digit 65533.
		for (let j = 0; frac > 0 && j < 4; j++) {
			frac *= 65533;
			const digit = Math.min(Math.floor(frac), 65532);
			frac -= digit;
			result += String.fromCharCode(2 + digit);
		}
		// A number followed by another part gets terminated by \x01, sorting below any
		// fraction digit, so that e.g. [2, "x"] sorts before [2.5, "x"].
		if (i < parts.length - 1) result += "\x01";
	}
	return result;
}

/**
 * Normalizes a sort key (as returned by a `makeSortKey` function, or an item's default key)
 * to the string form used for ordering item scopes, or null/undefined when the item should
 * not be shown.
 */
function normalizeSortKey(sortKey: SortKeyType | null): string | null | undefined {
	if (sortKey instanceof Array) return arrayToStr(sortKey);
	if (typeof sortKey !== "string" && sortKey != null) return arrayToStr([sortKey]);
	return sortKey as string | null | undefined; // `void` only exists in the type declaration
}

/**
 * Creates a new string that has the opposite sort order compared to the input string.
 *
 * This is achieved by flipping the bits of each character code in the input string.
 * The resulting string is intended for use as a sort key, particularly with the
 * `makeKey` function in {@link onEach}, to achieve a descending sort order.
 *
 * **Warning:** The output string will likely contain non-printable characters or
 * appear as gibberish and should not be displayed to the user.
 *
 * @example
 * ```typescript
 * const $users = A.proxy([
 *     { id: 1, name: 'Charlie', score: 95 },
 *     { id: 2, name: 'Alice', score: 100 },
 *     { id: 3, name: 'Bob', score: 90 },
 * ]);
 *
 * A.onEach($users, ($user) => {
 *     A(`p#${$user.name}: ${$user.score}`);
 * }, ($user) => A.invertString($user.name)); // Reverse alphabetic order
 * ```
 *
 * @param input The string whose sort order needs to be inverted.
 * @returns A new string that will sort in the reverse order of the input string.
 * @see {@link onEach} for usage with sorting.
 */
export function invertString(input: string): string {
	let result = "";
	for (let i = 0; i < input.length; i++) {
		result += String.fromCodePoint(65535 - input.charCodeAt(i));
	}
	return result;
}

// Each new scope gets a lower prio than all scopes before it, by decrementing
// this counter.
let lastPrio = 0;

abstract class Scope implements QueueRunner {
	// Scopes are to be handled in creation order. This will make sure that parents are
	// handled before their children (as they should), and observes are executed in the
	// order of the source code.
	prio: number = --lastPrio;

	[ptr: ReverseSortedSetPointer]: this;

	abstract onChange(target: TargetType, index: any, newData: any, oldData: any): void;
	abstract queueRun(): void;

	abstract getLastNode(): Node | undefined;
	abstract getPrecedingNode(): Node | undefined;
	abstract delete(): void;

	remove() {
		// Remove any nodes
		const lastNode = this.getLastNode();
		if (lastNode) removeNodes(lastNode, this.getPrecedingNode());

		// Run any cleaners. Our own element survives this teardown (we only removed our child
		// content above), so value-restoring cleaners registered for it should still run.
		const savedSurvivingEl = survivingEl;
		survivingEl = (this as any).el;
		this.delete();
		survivingEl = savedSurvivingEl;
	}

	// toString(): string {
	// 	return `${this.constructor.name}`
	// }
}

/**
 * Execute a function once, after all currently scheduled jobs are completed.
 */
class DelayedOneTimeRunner implements QueueRunner {
	prio: number = --lastPrio;
	[ptr: ReverseSortedSetPointer]: this;
	constructor(
		public queueRun: () => void
	) {
		queue(this);
	}
}

/**
 * All Scopes that can hold nodes and subscopes, including `SimpleScope` and `OnEachItemScope`
 * but *not* `OnEachScope`, are `ContentScope`s.
 */
abstract class ContentScope extends Scope {
	// The list of clean functions to be called when this scope is cleaned. These can
	// be for child scopes, subscriptions as well as `clean(..)` hooks.
	cleaners: Array<{ delete: (scope: Scope) => void } | (() => void)>;

	abstract svg: boolean;
	abstract el: Element;
	// Flat (type, key, value) triplets describing side-effects applied to our own element; see SideEffect.
	sideEffects: any[] | undefined;
	private changes: undefined | Map<TargetType, Map<any, any>>; // target => (index => oldData)

	constructor(
		cleaners: Array<{ delete: (scope: Scope) => void } | (() => void)> = [],
	) {
		super();
		this.cleaners = cleaners;
	}

	lastChild: Node | Scope | undefined;

	// Should be subclassed in most cases..
	redraw() {}

	getLastNode(): Node | undefined {
		return findLastNodeInPrevSiblings(this.lastChild);
	}

	/**
	 * Call cleaners and make sure the scope is not queued.
	 * It is called `delete`, so that the list of cleaners can also contain `Set`s.
	 */
	delete(/* ignore observer argument */) {
		// Run cleaners in reverse (LIFO) order. Child scopes live here too, so a nested scope that
		// shares our element gets to undo its (more recent) side-effects before we undo ours below.
		const cleaners = this.cleaners;
		for (let i = cleaners.length - 1; i >= 0; i--) {
			const cleaner = cleaners[i];
			if (typeof cleaner === "function") cleaner();
			else cleaner.delete(this); // pass in observer argument, in case `cleaner` is a `Set`
		}
		this.cleaners.length = 0;

		// Undo the side-effects we applied to our own element, in reverse (LIFO) order so the original
		// pre-scope value is restored. Only do this when our element survives the teardown; if it's
		// being removed from the DOM, reverting its attributes/classes/etc would be wasted work.
		const se = this.sideEffects;
		if (se) {
			if (this.el === survivingEl) undoSideEffects(this.el, se);
			this.sideEffects = undefined;
		}

		sortedQueue?.remove(this); // This is very fast and O(1) when not queued

		// To prepare for a redraw or to help GC when we're being removed:
		this.lastChild = undefined;
	}

	onChange(target: TargetType, index: any, newData: any, oldData: any): void {
		if (!this.changes) {
			this.changes = new Map();
			queue(this);
			dev?.schedule(this, index, oldData, newData, new Error());
		}

		let targetDelta = this.changes.get(target);
		if (!targetDelta) {
			targetDelta = new Map();
			this.changes.set(target, targetDelta);
		}

		if (targetDelta.has(index)) {
			// Already changed before, keep original oldData
			// Unless it changed back to original value
			if (targetDelta.get(index) === newData) targetDelta.delete(index);
		} else {
			targetDelta.set(index, oldData);
		}
	}

	fetchHasChanges(): boolean {
		if (!this.changes) return false;
		for(const targetDelta of this.changes.values()) {
			if (targetDelta.size > 0) {
				delete this.changes;
				return true;
			}
		}
		delete this.changes;
		return false;
	}
		

	queueRun() {
		if (!this.fetchHasChanges()) return;
		this.remove();

		topRedrawScope = this;
		this.redraw();
		topRedrawScope = undefined;
	}

	getInsertAfterNode() {
		return this.getLastNode() || this.getPrecedingNode();
	}

	getChildPrevSibling() {
		return this.lastChild;
	}
}

class ChainedScope extends ContentScope {
	// The node or scope right before this scope that has the same `parentElement`.
	public prevSibling: Node | Scope | undefined;

	constructor(
		// The parent DOM element we'll add our child nodes to.
		public el: Element,
		// Whether this scope is within an SVG namespace context
		public svg: boolean,
		// When true, we share our 'cleaners' list with the parent scope.
		useParentCleaners = false,
	) {
		super(useParentCleaners ? currentScope.cleaners : []);
		
		if (el === currentScope.el) {
			// If `currentScope` is not actually a ChainedScope, prevSibling will be undefined, as intended
			this.prevSibling = currentScope.getChildPrevSibling();
			currentScope.lastChild = this;
		} else {
			this.prevSibling = el.lastChild || undefined;
		}

		// We're always adding ourselve as a cleaner, in order to run our own cleaners
		// and to remove ourselve from the queue (if we happen to be in there).
		if (!useParentCleaners) currentScope.cleaners.push(this);

		// Covers RegularScope, ResultScope and SetArgScope; the enclosing render scope is the parent.
		dev?.create(this, currentScope, new Error());
	}

	getPrecedingNode(): Node | undefined {
		return findLastNodeInPrevSiblings(this.prevSibling);
	}

	getChildPrevSibling() {
		return this.lastChild || this.prevSibling;
	}
}

/**
 * @internal
 * A `RegularScope` is created with a `render` function that is run initially,
 * and again when any of the `Store`s that this function reads are changed. Any
 * DOM elements that is given a `render` function for its contents has its own scope.
 * The `Scope` manages the position in the DOM tree elements created by `render`
 * are inserted at. Before a rerender, all previously created elements are removed
 * and the `clean` functions for the scope and all sub-scopes are called.
 */
class RegularScope extends ChainedScope {
	constructor(
		el: Element,
		svg: boolean,
		// The function that will be reactively called. Elements it creates using `$` are
		// added to the appropriate position within `parentElement`.
		public renderer: () => any,
	) {
		super(el, svg);

		// Do the initial run
		this.redraw();
	}

	redraw() {
		const savedScope = currentScope;
		currentScope = this;
		dev?.render(this);
		try {
			this.renderer();
		} catch (e) {
			// Throw the error async, so the rest of the rendering can continue
			handleError(e, true);
		}
		currentScope = savedScope;
	}
}

class RootScope extends ContentScope {
	el = document.body;
	svg = false;
	getPrecedingNode(): Node | undefined {
		return undefined;
	}
}

class MountScope extends ContentScope {
	svg: boolean;
	constructor(
		// The parent DOM element we'll add our child nodes to
		public el: Element,
		// The function that
		public renderer: () => any,
	) {
		super();
		this.svg = el.namespaceURI === 'http://www.w3.org/2000/svg';

		// Register before the first redraw so its render is attributed to this scope.
		dev?.create(this, currentScope, new Error());

		const oldTopRedrawScope = topRedrawScope;
		topRedrawScope = this;
		this.redraw();
		topRedrawScope = oldTopRedrawScope;
		currentScope.cleaners.push(this);
	}

	redraw() {
		RegularScope.prototype.redraw.call(this);
	}

	getPrecedingNode(): Node | undefined {
		return undefined;
	}

	delete() {
		// We can't rely on our parent scope to remove all our nodes for us, as our parent
		// probably has a totally different `parentElement`. Therefore, our `delete()` does
		// what `_remove()` does for regular scopes.
		removeNodes(this.getLastNode(), this.getPrecedingNode());
		// Our mount element survives; reset the surviving element to it for our subtree's cleaners,
		// as our `el` differs from that of the (possibly removing) parent scope cascade.
		const savedSurvivingEl = survivingEl;
		survivingEl = this.el;
		super.delete();
		survivingEl = savedSurvivingEl;
	}

	remove() {
		this.delete();
	}
}

// Remove node and all its preceding siblings (uptil and excluding preNode)
// from the DOM, using onDestroy if applicable.
function removeNodes(
	node: Node | null | undefined,
	preNode: Node | null | undefined,
) {
	while (node && node !== preNode) {
		const prevNode: Node | null = node.previousSibling;
		const onDestroy = onDestroyMap.get(node);
		if (onDestroy && node instanceof Element) {
			if (onDestroy !== true) {
				if (typeof onDestroy === "function") {
					onDestroy(node);
				} else {
					destroyWithClass(node, onDestroy);
				}
				// This causes the element to be ignored from this function from now on:
				onDestroyMap.set(node, true);
			}
			// Ignore the deleting element
		} else {
			(node as Element | Text).remove();
		}
		node = prevNode;
	}
}

// Move `node` and all its preceding siblings (up to and excluding `preNode`) to just after
// `afterNode` (or to the start of `parentEl` when `afterNode` is undefined), preserving their
// order. Elements currently playing their destroy animation are left where they are, like
// `removeNodes` does. Uses `moveBefore` when the browser supports it, which keeps state such
// as focus, text selection, CSS animations and iframe documents intact. Otherwise
// `insertBefore` is used, which preserves the elements themselves (and things like `<input>`
// values), but resets such state.
function moveNodes(
	node: Node | undefined,
	preNode: Node | undefined,
	parentEl: Element,
	afterNode: Node | undefined,
) {
	// `moveBefore` throws when the parent (and thus the nodes) are not connected to the
	// document; `isConnected` is undefined in our fake test DOM, which is always "connected".
	const method =
		(parentEl as any).moveBefore && parentEl.isConnected !== false ? "moveBefore" : "insertBefore";
	// Walk backwards, moving each node to right before the previously moved one. The previous
	// sibling is captured before the move, as moving the node would upset our walk.
	let ref: Node | null = afterNode ? afterNode.nextSibling : parentEl.firstChild;
	while (node && node !== preNode) {
		const prevNode: Node | null = node.previousSibling;
		if (onDestroyMap.get(node) !== true) {
			(parentEl as any)[method](node, ref);
			ref = node;
		}
		node = prevNode || undefined;
	}
}

// Get a reference to the last node within `sibling` or any of its preceding siblings.
// If a `Node` is given, that node is returned.
function findLastNodeInPrevSiblings(
	sibling: Node | Scope | undefined,
): Node | undefined {
	if (!sibling || sibling instanceof Node) return sibling;
	return sibling.getLastNode() || sibling.getPrecedingNode();
}

class ResultScope<T> extends ChainedScope {
	public result: ValueRef<T> = optProxy({ value: undefined });

	constructor(
		public renderer: () => T,
	) {
		super(currentScope.el, currentScope.svg);
		this.redraw();
	}

	redraw() {
		const savedScope = currentScope;
		currentScope = this;
		try {
			this.result.value = this.renderer();
		} catch (e) {
			// Throw the error async, so the rest of the rendering can continue
			handleError(e, true);
		}
		currentScope = savedScope;
	}
}

/**
 * A `Scope` subclass optimized for reactively setting just a single element property
 * based on a proxied reference.
 */

class SetArgScope extends ChainedScope {
	public svg = false;
	constructor(
		el: Element,
		private key: string,
		private target: { value: any },
	) {
		super(el, el.namespaceURI === 'http://www.w3.org/2000/svg');
		this.redraw();
	}
	redraw() {
		const savedScope = currentScope;
		currentScope = this;
		applyArg(this.el, this.key, this.target.value);
		currentScope = savedScope;
	}
}

/** @internal */
class OnEachScope extends Scope {
	// biome-ignore lint/correctness/noInvalidUseBeforeDeclaration: circular, as currentScope is initialized with a Scope
	parentElement: Element = currentScope.el;
	prevSibling: Node | Scope | undefined;

	/** The data structure we are iterating */
	target: TargetType;

	/** All item scopes, by array index or object key. This is used for removing an item scope when its value
	 * disappears, and calling all subscope cleaners. */
	byIndex: Map<any, OnEachItemScope> = new Map();

	/** The reverse-ordered list of item scopes, not including those for which makeSortKey returned undefined. */
	sortedSet: ReverseSortedSet<OnEachItemScope, "sortKey"> = new ReverseSortedSet("sortKey");

	/** Indexes that have been created/removed and need to be handled in the next `queueRun`. */
	changedIndexes: Map<any, any> = new Map(); // index => old value

	constructor(
		proxy: TargetType,
		/** A function that renders an item */
		public renderer: (value: any, key: any) => void,
		/** A function returning a number/string/array that defines the position of an item */
		public makeSortKey?: (value: any, key: any) => SortKeyType,
	) {
		super();
		const target: TargetType = (this.target = (proxy as any)[TARGET_SYMBOL] || proxy);

		subscribe(target, ANY_SYMBOL, this);
		this.prevSibling = currentScope.getChildPrevSibling();
		currentScope.lastChild = this;

		currentScope.cleaners.push(this);

		// Register before creating item scopes, so they can attach under this scope.
		dev?.create(this, currentScope, new Error());

		// Do _addChild() calls for initial items
		if (target instanceof Array) {
			for (let i = 0; i < target.length; i++) {
				new OnEachItemScope(this, i, false);
			}
		} else {
			for (const key of (target instanceof Map ? target.keys() : target instanceof Set ? target.values() : Object.keys(target))) {
				new OnEachItemScope(this, key, false);
			}
		}
	}

	getPrecedingNode(): Node | undefined {
		return findLastNodeInPrevSiblings(this.prevSibling);
	}

	onChange(target: TargetType, index: any, newData: any, oldData: any) {
		// target === this.target
		if (!(target instanceof Array) || typeof index === "number") {
			if (this.changedIndexes.has(index)) {
				if (this.changedIndexes.get(index) === newData) {
					// Data changed back to original value, so ignore it
					this.changedIndexes.delete(index);
				}
				// Else, data changed a second time
			} else {
				// Initial data change
				this.changedIndexes.set(index, oldData);
				queue(this);
			}
		}
	}

	queueRun() {
		const indexes = this.changedIndexes;
		this.changedIndexes = new Map();
		for (const index of indexes.keys()) {
			const oldScope = this.byIndex.get(index);
			if (oldScope) {
				oldScope.remove();
				// The old item scope is discarded here (recreated below if it survives), so drop it
				// from the dev tree; a fresh OnEachItemScope re-attaches itself.
				dev?.delete(oldScope);
			}

			if (this.target instanceof Set || this.target instanceof Map ? this.target.has(index) : index in this.target) {
				// Item still exists
				new OnEachItemScope(this, index, true);
			} else {
				// Item has disappeared
				this.byIndex.delete(index);
			}
		}
		topRedrawScope = undefined;
	}

	delete() {
		// Propagate to all our subscopes
		for (const scope of this.byIndex.values()) {
			scope.delete();
		}

		sortedQueue?.remove(this); // This is very fast and O(1) when not queued

		// Help garbage collection:
		this.byIndex.clear();
		setTimeout(() => {
			// Unsure if this is a good idea. It takes time, but presumably makes things a lot easier for GC...
			this.sortedSet.clear();
		}, 1);
	}

	getLastNode(): Node | undefined {
		for (const scope of this.sortedSet) {
			// Iterates starting at last child scope.
			const node = scope.getActualLastNode();
			if (node) return node;
		}
	}
}

/** @internal */
class OnEachItemScope extends ContentScope {
	sortKey: string | null | undefined; // When null-ish, this scope is currently not showing in the list
	public el: Element;
	public svg: boolean;

	constructor(
		public parent: OnEachScope,
		public itemIndex: any,
		topRedraw: boolean,
	) {
		super();
		this.el = parent.parentElement;
		
		// Inherit SVG namespace state from current scope
		this.svg = currentScope.svg;

		this.parent.byIndex.set(this.itemIndex, this);

		// Okay, this is hacky. In case our first (actual) child is a ChainedScope, we won't be able
		// to provide it with a reliable prevSibling. Therefore, we'll pretend to be that sibling,
		// doing what's need for this case in `getLastNode`.
		// For performance, we prefer not having to create additional 'fake sibling' objects for each item.
		this.lastChild = this;

		// Don't register to be cleaned by parent scope, as the OnEachScope will manage this for us (for efficiency)

		// An onEach item is its own scope; its parent in the tree is the OnEachScope.
		dev?.create(this, this.parent, new Error());

		if (topRedraw) topRedrawScope = this;
		this.redraw();
	}

	getPrecedingNode(): Node | undefined {
		// As apparently we're interested in the node insert position, we'll need to become part
		// of the sortedSet now (if we weren't already).
		// This will do nothing and barely take any time of `this` is already part of the set:
		this.parent.sortedSet.add(this);

		const preScope = this.parent.sortedSet.prev(this);
		// As preScope should have inserted itself as its first child, this should
		// recursively call getPrecedingNode() on preScope in case it doesn't
		// have any actual nodes as children yet.
		if (preScope) return findLastNodeInPrevSiblings(preScope.lastChild);
		return this.parent.getPrecedingNode();
	}

	getLastNode(): Node | undefined {
		// Hack! As explain in the constructor, this getLastNode method actually
		// does not return the last node, but the preceding one.
		return this.getPrecedingNode();
	}

	getActualLastNode(): Node | undefined {
		let child = this.lastChild;

		while (child && child !== this) {
			if (child instanceof Node) return child;
			const node = child.getLastNode();
			if (node) return node;
			child = child.getPrecedingNode();
		}
	}

	queueRun() {
		/* c8 ignore next */
		if (currentScope !== ROOT_SCOPE) internalError(4);

		if (!this.fetchHasChanges()) return;
		this.fullRedraw();
	}

	/** Removes the item's rendered nodes, cleans its subscopes and subscriptions, and
	 * renders it afresh (which may change or clear its position among its siblings). */
	fullRedraw() {
		// We're not calling `remove` here, as we don't want to remove ourselves from
		// the sorted set. `redraw` will take care of that, if needed.
		// Also, we can't use `getLastNode` here, as we've hacked it to return the
		// preceding node instead.
		if (this.sortKey != null) {
			const lastNode = this.getActualLastNode();
			if (lastNode) removeNodes(lastNode, this.getPrecedingNode());
		}

		// Our `el` (the list's parent element) survives; restore its value-restoring cleaners.
		const savedSurvivingEl = survivingEl;
		survivingEl = this.el;
		this.delete();
		survivingEl = savedSurvivingEl;
		this.lastChild = this; // apply the hack (see constructor) again

		topRedrawScope = this;
		this.redraw();
		topRedrawScope = undefined;
	}

	/** Returns the (proxied) `[value, key]` pair for this item, as passed to the user's
	 * `render` and `makeSortKey` functions. */
	getValueAndIndex(): [any, any] {
		const target = this.parent.target;
		let itemIndex = this.itemIndex;
		let value: any;
		if (target instanceof Set) {
			value = itemIndex = optProxy(itemIndex);
		} else if (target instanceof Map) {
			value = optProxy(target.get(itemIndex));
			// For Maps, the key may be an object. If so, we'll proxy it as well.
			itemIndex = optProxy(itemIndex);
		} else {
			value = optProxy((target as any)[itemIndex]);
		}
		return [value, itemIndex];
	}

	redraw() {
		// Note that we're NOT subscribing on target[itemIndex], as the OnEachScope uses
		// a wildcard subscription to delete/recreate any scopes when that changes.
		// We ARE creating a proxy around the value though (in case its an object/array),
		// so we'll have our own scope subscribe to changes on that.
		const [value, itemIndex] = this.getValueAndIndex();

		// Since makeSortKey may get() the Store, we'll need to set currentScope first.
		const savedScope = currentScope;
		currentScope = this;
		dev?.render(this);

		let sortKey: string | null | undefined;
		try {
			if (this.parent.makeSortKey) {
				// The sort key is computed in a (sub)scope of its own, so that a change
				// affecting only the key (and not the rendered content) can reposition
				// the item without redrawing it.
				sortKey = new SortKeyScope(this).compute(value, itemIndex);
			} else {
				sortKey = normalizeSortKey(itemIndex);
			}

			if (this.sortKey !== sortKey) {
				// If the sortKey is changed, make sure `this` is removed from the
				// set before setting the new sortKey to it.
				this.parent.sortedSet.remove(this); // Very fast if `this` is not in the set
				this.sortKey = sortKey;
			}

			// We're not adding `this` to the `sortedSet` (yet), as that may not be needed,
			// in case no nodes are created. We'll do it just-in-time in `getPrecedingNode`.

			if (sortKey != null) this.parent.renderer(value, itemIndex);
		} catch (e) {
			handleError(e, sortKey != null);
		}

		currentScope = savedScope;
	}

	getInsertAfterNode() {
		if (this.sortKey == null) internalError(1);
		// Due to the `this` being the first child for `this` hack, this will look
		// for the preceding node as well, if we don't have nodes ourselves.
		return findLastNodeInPrevSiblings(this.lastChild);
	}

	/** Repositions this item to match a changed `newKey`, moving its DOM nodes to their new
	 * position without redrawing them. Requires both the old and the new sort key to be
	 * non-null (meaning the item stays visible, and its content is unaffected). */
	move(newKey: string) {
		// Determine the current node range before changing our position. An item that has
		// rendered any nodes is always part of the sortedSet, as inserting a node requires
		// looking up its position through getPrecedingNode().
		const lastNode = this.getActualLastNode();
		const precedingNode = lastNode && this.getPrecedingNode();

		this.parent.sortedSet.remove(this);
		this.sortKey = newKey;

		// Without nodes there is nothing to move; we'll rejoin the sortedSet just-in-time
		// (see getPrecedingNode), like after a redraw.
		if (!lastNode) return;

		// This re-adds us to the sortedSet (now at the new position), and returns the node
		// after which our nodes should go from now on.
		const afterNode = this.getPrecedingNode();

		if (afterNode !== precedingNode) moveNodes(lastNode, precedingNode, this.el, afterNode);
	}

	remove() {
		// We can't use getLastNode here, as we've hacked it to return the preceding
		// node instead.
		if (this.sortKey != null) {
			const lastNode = this.getActualLastNode();
			if (lastNode) removeNodes(lastNode, this.getPrecedingNode());

			this.parent.sortedSet.remove(this);
			this.sortKey = undefined;
		}

		// Our `el` (the list's parent element) survives the removal of just this item.
		const savedSurvivingEl = survivingEl;
		survivingEl = this.el;
		this.delete();
		survivingEl = savedSurvivingEl;
	}
}

/** @internal
 * Computes an item's sort key within a scope of its own, so that a change to observable data
 * read by `makeSortKey` (but not by the item's render function) can reposition the item
 * without redrawing it. Created only when `onEach` was given a `makeSortKey` function. A full
 * (re)render of the item deletes this scope (through the item's cleaners) and creates a
 * fresh one.
 */
class SortKeyScope extends ContentScope {
	el: Element;
	svg: boolean;

	constructor(public item: OnEachItemScope) {
		super();
		this.el = item.el;
		this.svg = item.svg;

		// Have the item scope clean us up when it redraws or is removed.
		item.cleaners.push(this);

		dev?.create(this, item, new Error());
	}

	/** Runs `makeSortKey` with `this` as the subscribing scope, returning the normalized
	 * key. Exceptions propagate to the caller. */
	compute(value: any, itemIndex: any): string | null | undefined {
		const savedScope = currentScope;
		currentScope = this;
		dev?.render(this);
		try {
			return normalizeSortKey(this.item.parent.makeSortKey!(value, itemIndex));
		} finally {
			currentScope = savedScope;
		}
	}

	queueRun() {
		if (!this.fetchHasChanges()) return;

		const item = this.item;
		const oldKey = item.sortKey;

		// Drop the subscriptions of the previous computation; compute() will re-establish them.
		this.delete();

		let newKey: string | null | undefined;
		try {
			newKey = this.compute(...item.getValueAndIndex());
		} catch (e) {
			handleError(e, false);
			newKey = undefined;
		}

		if (newKey === oldKey || (newKey == null && oldKey == null)) return; // Position unaffected.

		if (newKey == null || oldKey == null) {
			// The item is toggling between shown and hidden, which changes what is rendered:
			// fall back to a full redraw. (This also deletes `this`, creating a fresh
			// SortKeyScope that recomputes the key.)
			item.fullRedraw();
		} else {
			// Only the position changed: move the item's DOM nodes without redrawing them.
			item.move(newKey);
		}
	}

	/* c8 ignore next 3 -- satisfies the abstract contract; we hold no nodes, so it's never called */
	getPrecedingNode(): undefined {
		return undefined;
	}

	getInsertAfterNode(): Node | undefined {
		throw new Error("makeSortKey must not create DOM nodes");
	}
}

function addNode(el: Element, node: Node) {
	if (el !== currentScope.el) {
		el.appendChild(node);
		dev?.node(currentScope, node, false);
		return;
	}
	const parentEl = currentScope.el;
	const prevNode = currentScope.getInsertAfterNode();
	parentEl.insertBefore(
		node,
		prevNode ? prevNode.nextSibling : parentEl.firstChild,
	);
	currentScope.lastChild = node;
	dev?.node(currentScope, node, true);
}

/**
 * This global is set during the execution of a `Scope.render`. It is used by
 * functions like `$` and `clean`.
 */
const ROOT_SCOPE = new RootScope();
let currentScope: ContentScope = ROOT_SCOPE;

// === Developer tools instrumentation =======================================
// The core emits events through `dev(type, ...args)` only when the dev tools are connected.
// The tools — the scope tree, node→scope / element→scope maps, stack traces, the UI, and the
// `?abdev=1` / Ctrl-Alt-A bootstrap — all live in `./devtools`, which *wraps* this module:
// in a dev build the `aberdeen` entry point is that wrapper, and it installs the sink via
// `A._setDev` synchronously at load (before the app's first `mount()`, so no buffering).
//
// There is deliberately no build-time flag: the hooks are always present, costing only a
// nullish check (`dev?.x(…)` doesn't even evaluate its arguments — no `new Error()`) when no
// tools are attached. Keeping them unconditional avoids the footgun of a stripped core being
// paired with the wrapper, or vice-versa.

/** @internal The instrumentation hooks the dev tools install via {@link _setDev}. Scopes are
 * passed opaquely (`any`); the tools read `.constructor.name`, `.el`, etc. off them. */
export interface DevHooks {
	/** A scope was created under `parent` (its onEach scope, for items); `err` holds the creation
	 * stack, or is `undefined` for scopes replayed on connect (they predate the tools). */
	create(scope: any, parent: any, err: Error | undefined): void;
	/** A scope is about to (re)render, replacing the DOM nodes and child scopes it last produced. */
	render(scope: any): void;
	/** A proxy change (`target[index]`, `oldData`→`newData`) scheduled `scope` to re-render; `err` holds the triggering stack. */
	schedule(scope: any, index: any, oldData: any, newData: any, err: Error): void;
	/** `scope` inserted DOM `node`; `top` marks a direct sibling at the scope's own level (vs. a descendant). */
	node(scope: any, node: Node, top: boolean): void;
	/** `scope` subscribed to `target[index]`. */
	read(scope: any, target: any, index: any): void;
	/** `scope` was permanently removed (an onEach item that no longer exists). */
	delete(scope: any): void;
}

/** @internal Event sink, installed by the dev-tools wrapper via {@link _setDev}. */
let dev: DevHooks | undefined;

/** @internal Install (or, with `undefined`, remove) the dev-tools hooks. Used by the
 * `./devtools` wrapper. A named `@internal` export (rather than an `A` member) so it is
 * stripped from the public type declarations.
 *
 * On connect the *already existing* scope tree is replayed as `create` events (with no
 * stack — those scopes predate the tools), so the tool shows the current tree immediately,
 * not only what changes afterwards. Their child scopes live in `cleaners` (and onEach items
 * in `byIndex`); nodes/reads/stacks for them fill in naturally as they re-render. */
export function _setDev(hooks: DevHooks | undefined) {
	dev = hooks;
	if (!hooks) return;
	const childScopes = (scope: any): Scope[] =>
		scope instanceof OnEachScope
			? [...scope.byIndex.values()]
			: (scope.cleaners as any[]).filter((c): c is Scope => c instanceof Scope);
	const replay = (scope: Scope, parent: Scope) => {
		hooks.create(scope, parent, undefined);
		for (const child of childScopes(scope)) replay(child, scope);
	};
	for (const child of childScopes(ROOT_SCOPE)) replay(child, ROOT_SCOPE);
}
// === End developer tools instrumentation ===================================

/**
 * Execute a function in a never-cleaned root scope. Even {@link unmountAll} will not
 * clean up observers/nodes created by the function.
 * @param func The function to execute.
 * @returns The return value of the function.
 * @internal
 */
export function leakScope<T>(func: () => T): T {
	const savedScope = currentScope;
	currentScope = new RootScope();
	try {
		return func();
	} finally {
		currentScope = savedScope;
	}
}

/**
 * A special Node observer index to subscribe to any value in the map changing.
 */
const ANY_SYMBOL = Symbol("any");

/**
 * When our proxy objects need to lookup `obj[TARGET_SYMBOL]` it returns its
 * target, to be used in our wrapped methods.
 */
const TARGET_SYMBOL = Symbol("target");

/**
 * Symbol used internally to track Map and Set size without clashing with actual Map keys named "size".
 * 
 * @internal
 */
export const MAP_SIZE_SYMBOL = Symbol("mapSize");

const subscribers = new WeakMap<
	TargetType,
	Map<
		any,
		Set<Scope | ((index: any, newData: any, oldData: any) => void)>
	>
>();
let peeking = 0; // When > 0, we're not subscribing to any changes

function subscribe(
	target: any,
	index: symbol | string | number,
	observer:
		| Scope
		| ((
				index: any,
				newData: any,
				oldData: any,
		  ) => void) = currentScope,
) {
	if (observer === ROOT_SCOPE || peeking) return;

	if (observer === currentScope) dev?.read(currentScope, target, index);

	let byTarget = subscribers.get(target);
	if (!byTarget) subscribers.set(target, (byTarget = new Map()));

	// No need to subscribe to specific keys if we're already subscribed to ANY
	if (index !== ANY_SYMBOL && byTarget.get(ANY_SYMBOL)?.has(observer)) return;

	let byIndex = byTarget.get(index);
	if (!byIndex) byTarget.set(index, (byIndex = new Set()));

	if (byIndex.has(observer)) return;

	byIndex.add(observer);

	if (observer === currentScope) {
		currentScope.cleaners.push(byIndex);
	} else {
		currentScope.cleaners.push(() => {
			byIndex.delete(observer);
		});
	}
}

/**
 * Records in TypeScript pretend that they can have number keys, but in reality they are converted to string.
 * This type changes (number | something) types to (string | something) types, maintaining typing precision as much as possible.
 * @internal
 */
type KeyToString<K> = K extends number ? string : K extends string | symbol ? K : K extends number | infer U ? string | U : K;

export function onEach<K, T>(
	target: Map<K, undefined | T>,
	render: (value: T, key: K) => void,
	makeKey?: (value: T, key: K) => SortKeyType,
): void;
export function onEach<T>(
	target: Set<T>,
	render: (value: T) => void,
	makeKey?: (value: T) => SortKeyType,
): void;
export function onEach<T>(
	target: ReadonlyArray<undefined | T>,
	render: (value: T, index: number) => void,
	makeKey?: (value: T, index: number) => SortKeyType,
): void;
export function onEach<K extends string | number | symbol, T>(
	target: Record<K, undefined | T>,
	render: (value: T, index: KeyToString<K>) => void,
	makeKey?: (value: T, index: KeyToString<K>) => SortKeyType,
): void;

/**
 * Reactively iterates over the items of an observable array, object, Map, or Set, optionally rendering content for each item.
 *
 * Automatically updates when items are added, removed, or modified.
 *
 * @param target The observable array, object, Map, or Set to iterate over. Values that are `undefined` are skipped.
 * @param render A function called for each item. It receives the item's (observable) value and its index/key. For Sets, only the value is provided. Any DOM elements created within this function will be associated with the item, placed at the right spot in the DOM, and cleaned up when redrawing/removing the item.
 * @param makeKey An optional function to generate a sort key for each item. This controls the order in which items are rendered in the DOM. If omitted, arrays use index order, Sets use the item value itself, and objects/Maps use their natural key order. The returned key can be a number, string, or an array of numbers/strings for composite sorting. Use {@link invertString} on string keys for descending order. Returning `null` or `undefined` from `makeKey` will prevent the item from being rendered.
 *
 * `makeKey` runs in a reactive scope of its own: when observable data it reads changes the resulting key, the item's DOM nodes are *moved* to their new position without being redrawn (so state like `<input>` values survives, and — in browsers supporting the `moveBefore` API — focus, text selection and CSS animations do too). Changes that switch the key between `null`-ish and an actual value show/hide the item, and therefore do cause a (re)render. `makeKey` must not create DOM nodes.
 *
 * @example Iterating an array
 * ```typescript
 * const $items = A.proxy(['apple', 'banana', 'cherry']);
 *
 * // Basic iteration
 * A.onEach($items, (item, index) => A(`li#${item} (#${index})`));
 *
 * // Add a new item - the list updates automatically
 * setTimeout(() => $items.push('durian'), 2000);
 * // Same for updates and deletes
 * setTimeout(() => $items[1] = 'berry', 4000);
 * setTimeout(() => delete $items[2], 6000);
 * ```
 *
 * @example Iterating an array with custom ordering
 * ```typescript
 * const $users = A.proxy([
 *     { id: 3, group: 1, name: 'Charlie' },
 *     { id: 1, group: 1, name: 'Alice' },
 *     { id: 2, group: 2, name: 'Bob' },
 * ]);
 *
 * // Sort by name alphabetically
 * A.onEach($users, ($user) => {
 *     A(`p#${$user.name} (id=${$user.id})`);
 * }, ($user) => [$user.group, $user.name]); // Sort by group, and within each group sort by name
 * ```
 *
 *  @example Iterating an object
 * ```javascript
 * const $config = A.proxy({ theme: 'dark', fontSize: 14, showTips: true });
 *
 * // Display configuration options
 * A('dl', () => {
 *     A.onEach($config, (value, key) => {
 *         if (key === 'showTips') return; // Don't render this one
 *         A('dt#'+key);
 *         A('dd#'+value);
 *     });
 * });
 *
 * // Change a value - the display updates automatically
 * setTimeout(() => $config.fontSize = 16, 2000);
 * ```
 *
 * @example Iterating a Set
 * ```javascript
 * const $tags = A.proxy(new Set(['ui', 'fast', 'tiny']));
 *
 * A('ul', () => {
 *     A.onEach($tags, (tag) => { // Defaults to alphabetically ordering by tag
 *         A(`li#${tag}`);
 *     });
 * });
 *
 * setTimeout(() => $tags.add('reactive'), 2000);
 * ```
 * @see {@link invertString} To easily create keys for reverse sorting.
 */
export function onEach(
	target: TargetType,
	render: (value: any, index: any) => void,
	makeKey?: (value: any, key: any) => SortKeyType,
): void {
	if (!target || typeof target !== "object")
		throw new Error("A.onEach requires an object");
	target = (target as any)[TARGET_SYMBOL] || target;

	new OnEachScope(target, render, makeKey);
}

function isObjEmpty(obj: object): boolean {
	for (const k of Object.keys(obj)) return false;
	return true;
}

/** @private */
export const EMPTY = Symbol("empty");

/**
 * Reactively checks if an observable array, object, Map, or Set is empty.
 *
 * This function not only returns the current emptiness state but also establishes
 * a reactive dependency. If the emptiness state of the `proxied` object or array
 * changes later (e.g., an item is added to an empty array, or the last property
 * is deleted from an object), the scope that called `isEmpty` will be automatically
 * scheduled for re-evaluation.
 *
 * @param proxied The observable array, object, Map, or Set to check.
 * @returns `true` if the array has length 0, the Map/Set has size 0, or the object has no own enumerable properties, `false` otherwise.
 *
 * @example
 * ```typescript
 * const $items = A.proxy([]);
 *
 * // Reactively display a message if the items array is empty
 * A('div', () => {
 *     if (A.isEmpty($items)) {
 *         A('p i#No items yet!');
 *     } else {
 *         A.onEach($items, item => A('p#'+item));
 *     }
 * });
 *
 * // Adding an item will automatically remove the "No items yet!" message
 * setInterval(() => {
 *   if (!$items.length || Math.random()>0.5) $items.push('Item');
 *   else $items.length = 0;
 * }, 1000)
 * ```
 */
export function isEmpty(proxied: TargetType): boolean {
	const target = (proxied as any)[TARGET_SYMBOL] || proxied;
	const scope = currentScope;

	if (target instanceof Array) {
		subscribe(target, "length", (index: any, newData: any, oldData: any) => {
			if (!newData !== !oldData) scope.onChange(target, EMPTY, !newData, !oldData);
		});
		return !target.length;
	}
	
	if (target instanceof Map || target instanceof Set) {
		subscribe(target, MAP_SIZE_SYMBOL, (index: any, newData: any, oldData: any) => {
			if (!newData !== !oldData) scope.onChange(target, EMPTY, !newData, !oldData);
		});
		return !target.size;
	}
	
	let oldEmpty = isObjEmpty(target);
	subscribe(target, ANY_SYMBOL, (index: any, newData: any, oldData: any) => {
		if ((newData === EMPTY) !== (oldData === EMPTY)) {
			const newEmpty = isObjEmpty(target);
			if (newEmpty !== oldEmpty) {
				scope.onChange(target, EMPTY, newEmpty, oldEmpty);
				oldEmpty = newEmpty;
			}
		}
	});
	return oldEmpty;
}

/** @private */
export interface ValueRef<T> {
	value: T;
}

/**
 * Reactively counts the number of properties in an object.
 *
 * @param proxied The observable object to count. In case an `array`, `Map`, or `Set` is passed in, a {@link ref} to its `.length` or `.size` will be returned.
 * @returns an observable object for which the `value` property reflects the number of properties in `proxied` with a value other than `undefined`, or the collection size for arrays, Maps, and Sets.
 * 
 * @example
 * ```typescript
 * const $items = A.proxy({x: 3, y: 7} as any);
 * const $count = A.count($items);
 *
 * // Create a DOM text node for the count:
 * A('div text=', $count);
 * // <div>2</div>

 * // Or we can use it in an {@link derive} function:
 * A(() => console.log("The count is now", $count.value));
 * // The count is now 2
 * 
 * // Adding/removing items will update the count
 * $items.z = 12;
 * // Asynchronously, after 0ms:
 * // <div>3</div>
 * // The count is now 3
 * ```
 */
export function count(proxied: TargetType): ValueRef<number> {
	if (proxied instanceof Array) return ref(proxied, "length");
	if (proxied instanceof Map || proxied instanceof Set) return ref(proxied, "size");

	const target = (proxied as any)[TARGET_SYMBOL] || proxied;
	let cnt = 0;
	for (const k of Object.keys(target)) if (target[k] !== undefined) cnt++;

	const result = proxy(cnt);
	subscribe(
		target,
		ANY_SYMBOL,
		(index: any, newData: any, oldData: any) => {
			if (oldData === newData) {
			} else if (oldData === EMPTY) result.value = ++cnt;
			else if (newData === EMPTY) result.value = --cnt;
		},
	);

	return result;
}

/** @internal */
export function defaultEmitHandler(
	target: TargetType,
	index: string | symbol | number,
	newData: any,
	oldData: any,
) {
	// We're triggering for values changing from undefined to undefined, as this *may*
	// indicate a change from or to `[empty]` (such as `[,1][0]`).
	if (newData === oldData && newData !== undefined) return;

	const byTarget = subscribers.get(target);
	if (byTarget === undefined) return;

	for (const what of [index, ANY_SYMBOL]) {
		const byIndex = byTarget.get(what);
		if (byIndex) {
			for (const observer of byIndex) {
				if (typeof observer === "function") observer(index, newData, oldData);
				else observer.onChange(target, index, newData, oldData);
			}
		}
	}
}
let emit = defaultEmitHandler;

const objectHandler: ProxyHandler<any> = {
	get(target: any, prop: any) {
		if (prop === TARGET_SYMBOL) return target;
		subscribe(target, prop);
		return optProxy(target[prop]);
	},
	set(target: any, prop: any, newData: any) {
		// Make sure newData is unproxied
		if (typeof newData === "object" && newData)
			newData = (newData as any)[TARGET_SYMBOL] || newData;
		const oldData = target.hasOwnProperty(prop) ? target[prop] : EMPTY;
		if (newData !== oldData) {
			target[prop] = newData;
			emit(target, prop, newData, oldData);
		}
		return true;
	},
	deleteProperty(target: any, prop: any) {
		const old = target.hasOwnProperty(prop) ? target[prop] : EMPTY;
		delete target[prop];
		emit(target, prop, EMPTY, old);
		return true;
	},
	has(target: any, prop: any) {
		subscribe(target, prop);
		return target.hasOwnProperty(prop);
	},
	ownKeys(target: any) {
		subscribe(target, ANY_SYMBOL);
		return Reflect.ownKeys(target);
	},
};

function arraySet(target: any, prop: any, newData: any) {
	// Make sure newData is unproxied
	if (typeof newData === "object" && newData) {
		newData = (newData as any)[TARGET_SYMBOL] || newData;
	}
	let oldData = target[prop];
	if (oldData === undefined && !target.hasOwnProperty(prop)) oldData = EMPTY;
	if (newData !== oldData) {
		const oldLength = target.length;

		if (prop === "length") {
			target.length = newData;

			// We only need to emit for shrinking, as growing just adds undefineds
			for (let i = newData; i < oldLength; i++) {
				emit(target, i, EMPTY, target[i]);
			}
		} else {
			if (typeof prop === 'string') { // Convert to int when possible
				const n = 0|prop as any;
				if (String(n) === prop && n >= 0) prop = n;
			}

			target[prop] = newData;
			emit(target, prop, newData, oldData);
		}
		if (target.length !== oldLength) {
			emit(target, "length", target.length, oldLength);
		}
	}
	return true;
}

const arrayHandler: ProxyHandler<any[]> = {
	get(target: any, prop: any) {
		if (prop === TARGET_SYMBOL) return target;
		if (typeof prop === 'string') { // Convert to int when possible
			const n = 0|prop as any;
			if (String(n) === prop && n >= 0) prop = n;
		}
		subscribe(target, prop);
		return optProxy(target[prop]);
	},
	set: arraySet,
	deleteProperty(target: any, prop: any) {
		if (typeof prop === 'string') { // Convert to int when possible
			const n = 0|prop as any;
			if (String(n) === prop && n >= 0) prop = n;
		}
		let oldData = target[prop];
		if (oldData === undefined && !target.hasOwnProperty(prop)) oldData = EMPTY;
		delete target[prop];
		emit(target, prop, EMPTY, oldData);
		return true;
	},
};

/**
 * Helper functions that wrap iterators to proxy values
 */
function wrapIteratorSingle(iterator: IterableIterator<any>): IterableIterator<any> {
	return {
		[Symbol.iterator]() { return this; },
		next() {
			const result = iterator.next();
			if (result.done) return result;
			return {
				done: false,
				value: optProxy(result.value)
			};
		}
	};
}
function wrapIteratorPair(iterator: IterableIterator<[any, any]>): IterableIterator<[any, any]> {
	return {
		[Symbol.iterator]() { return this; },
		next() {
			const result = iterator.next();
			if (result.done) return result;
			return {
				done: false,
				value: [optProxy(result.value[0]), optProxy(result.value[1])]
			};
		}
	};
}

function unproxyCollectionValue<T>(value: T): T {
	return typeof value === "object" && value ? ((value as any)[TARGET_SYMBOL] || value) : value;
}

const mapMethodHandlers = {
	get(this: any, key: any): any {
		const target: Map<any, any> = this[TARGET_SYMBOL];
		key = unproxyCollectionValue(key);
		subscribe(target, key);
		return optProxy(target.get(key));
	},
	set(this: any, key: any, newData: any): any {
		const target: Map<any, any> = this[TARGET_SYMBOL];
		key = unproxyCollectionValue(key);
		newData = unproxyCollectionValue(newData);
		let oldData = target.get(key);
		if (oldData === undefined && !target.has(key)) oldData = EMPTY;
		if (newData !== oldData) {
			const oldSize = target.size;
			target.set(key, newData);
			emit(target, key, newData, oldData);
			emit(target, MAP_SIZE_SYMBOL, target.size, oldSize);
		}
		return this;
	},
	delete(this: any, key: any): boolean {
		const target: Map<any, any> = this[TARGET_SYMBOL];
		key = unproxyCollectionValue(key);
		let oldData = target.get(key);
		if (oldData === undefined && !target.has(key)) oldData = EMPTY;
		const result: boolean = target.delete(key);
		if (result) {
			emit(target, key, EMPTY, oldData);
			emit(target, MAP_SIZE_SYMBOL, target.size, target.size + 1);
		}
		return result;
	},
	clear(this: any): void {
		const target: Map<any, any> = this[TARGET_SYMBOL];
		const oldSize = target.size;
		for (const key of target.keys()) {
			emit(target, key, undefined, target.get(key));
		}
		target.clear();
		emit(target, MAP_SIZE_SYMBOL, 0, oldSize);
	},
	has(this: any, key: any): boolean {
		const target: Map<any, any> = this[TARGET_SYMBOL];
		key = unproxyCollectionValue(key);
		subscribe(target, key);
		return target.has(key);
	},
	keys(this: any): IterableIterator<any> {
		const target: Map<any, any> = this[TARGET_SYMBOL];
		subscribe(target, ANY_SYMBOL);
		return wrapIteratorSingle(target.keys());
	},
	values(this: any): IterableIterator<any> {
		const target: Map<any, any> = this[TARGET_SYMBOL];
		subscribe(target, ANY_SYMBOL);
		return wrapIteratorSingle(target.values());
	},
	entries(this: any): IterableIterator<[any, any]> {
		const target: Map<any, any> = this[TARGET_SYMBOL];
		subscribe(target, ANY_SYMBOL);
		return wrapIteratorPair(target.entries());
	},
	[Symbol.iterator](this: any): IterableIterator<[any, any]> {
		const target: Map<any, any> = this[TARGET_SYMBOL];
		subscribe(target, ANY_SYMBOL);
		return wrapIteratorPair(target[Symbol.iterator]());
	}
};

const setMethodHandlers = {
	add(this: any, value: any): any {
		const target: Set<any> = this[TARGET_SYMBOL];
		value = unproxyCollectionValue(value);
		if (!target.has(value)) {
			const oldSize = target.size;
			target.add(value);
			emit(target, value, value, EMPTY);
			emit(target, MAP_SIZE_SYMBOL, target.size, oldSize);
		}
		return this;
	},
	delete(this: any, value: any): boolean {
		const target: Set<any> = this[TARGET_SYMBOL];
		value = unproxyCollectionValue(value);
		if (!target.has(value)) return false;
		const oldSize = target.size;
		target.delete(value);
		emit(target, value, EMPTY, value);
		emit(target, MAP_SIZE_SYMBOL, target.size, oldSize);
		return true;
	},
	clear(this: any): void {
		const target: Set<any> = this[TARGET_SYMBOL];
		const oldSize = target.size;
		if (!oldSize) return;
		for (const value of target.values()) emit(target, value, EMPTY, value);
		target.clear();
		emit(target, MAP_SIZE_SYMBOL, 0, oldSize);
	},
	has(this: any, value: any): boolean {
		const target: Set<any> = this[TARGET_SYMBOL];
		value = unproxyCollectionValue(value);
		subscribe(target, value);
		return target.has(value);
	},
	keys(this: any): IterableIterator<any> {
		const target: Set<any> = this[TARGET_SYMBOL];
		subscribe(target, ANY_SYMBOL);
		return wrapIteratorSingle(target.keys());
	},
	values(this: any): IterableIterator<any> {
		const target: Set<any> = this[TARGET_SYMBOL];
		subscribe(target, ANY_SYMBOL);
		return wrapIteratorSingle(target.values());
	},
	entries(this: any): IterableIterator<[any, any]> {
		const target: Set<any> = this[TARGET_SYMBOL];
		subscribe(target, ANY_SYMBOL);
		return wrapIteratorPair(target.entries());
	},
	[Symbol.iterator](this: any): IterableIterator<any> {
		const target: Set<any> = this[TARGET_SYMBOL];
		subscribe(target, ANY_SYMBOL);
		return wrapIteratorSingle(target[Symbol.iterator]());
	}
};

const mapHandler: ProxyHandler<Map<any, any>> = {
	get(target: Map<any, any>, prop: any) {
		if (prop === TARGET_SYMBOL) return target;
		
		// Handle Map methods using lookup object
		if (mapMethodHandlers.hasOwnProperty(prop)) {
			return (mapMethodHandlers as any)[prop];
		}
		
		// Handle size property
		if (prop === "size") {
			subscribe(target, MAP_SIZE_SYMBOL);
			return target.size;
		}
		
		// Handle other properties normally
		return (target as any)[prop];
	},
};

const setHandler: ProxyHandler<Set<any>> = {
	get(target: Set<any>, prop: any) {
		if (prop === TARGET_SYMBOL) return target;

		if (setMethodHandlers.hasOwnProperty(prop)) {
			return (setMethodHandlers as any)[prop];
		}

		if (prop === "size") {
			subscribe(target, MAP_SIZE_SYMBOL);
			return target.size;
		}

		return (target as any)[prop];
	},
};

const proxyMap = new WeakMap<TargetType, /*Proxy*/ TargetType>();

function optProxy(value: any): any {
	// If value is a primitive type or already proxied, just return it
	if (
		typeof value !== "object" ||
		value === null ||
		value[TARGET_SYMBOL] !== undefined ||
		value[OPAQUE]
	) {
		return value;
	}
	let proxied = proxyMap.get(value);
	if (proxied) return proxied; // Only one proxy per target!

	let handler;
	if (value instanceof Array) {
		handler = arrayHandler;
	} else if (value instanceof Map) {
		handler = mapHandler;
	} else if (value instanceof Set) {
		handler = setHandler;
	} else {
		handler = objectHandler;
	}

	proxied = new Proxy(value, handler);
	proxyMap.set(value, proxied as TargetType);
	return proxied;
}

/**
 * When `proxy` is called with a Promise, the returned object has this shape.
 */
export interface PromiseProxy<T> {
	/**
	 * True if the promise is still pending, false if it has resolved or rejected.
	 */
	busy: boolean;
	/**
	 * If the promise has resolved, this contains the resolved value.
	 */
	value?: T;
	/**
	 * If the promise has rejected, this contains the rejection error.
	 */
	error?: any;
}

export function proxy<T extends any>(target: Promise<T>): PromiseProxy<T>;
export function proxy<T extends any>(target: Array<T>): Array<T extends number ? number : T extends string ? string : T extends boolean ? boolean : T >;
export function proxy<T extends object>(target: T): T;
export function proxy<T extends any>(target: T): ValueRef<T extends number ? number : T extends string ? string : T extends boolean ? boolean : T>;

/**
 * Creates a reactive proxy around the given data.
 *
 * Reading properties from the returned proxy within a reactive scope (like one created by
 * {@link A | A} or {@link derive}) establishes a subscription. Modifying properties *through*
 * the proxy will notify subscribed scopes, causing them to re-execute.
 *
 * - Plain objects, arrays, Maps, and Sets are wrapped in a standard JavaScript `Proxy` that intercepts
 *   property access and mutations, but otherwise works like the underlying data.
 * - Primitives (string, number, boolean, null, undefined) are wrapped in an object
 *   `{ value: T }` which is then proxied. Access the primitive via the `.value` property.
 * - Promises are represented by proxied objects `{ busy: boolean, value?: T, error?: any }`.
 *   Initially, `busy` is `true`. When the promise resolves, `value` is set and `busy`
 *   is set to `false`. If the promise is rejected, `error` is set and `busy` is also
 *   set to `false`.
 *
 * Use {@link unproxy} to get the original underlying data back.
 * By convention in the examples below, local variables that hold proxied values are prefixed with `$`.
 *
 * @param target - The object, array, Map, Set, or primitive value to make reactive.
 * @returns A reactive proxy wrapping the target data.
 * @template T - The type of the data being proxied.
 *
 * @example Object
 * ```javascript
 * const $state = A.proxy({ count: 0, message: 'Hello' });
 * A(() => console.log($state.message)); // Subscribes to message
 * setTimeout(() => $state.message = 'World', 1000); // Triggers the observing function
 * setTimeout(() => $state.count++, 2000); // Triggers nothing
 * ```
 *
 * @example Array
 * ```javascript
 * const $items = A.proxy(['a', 'b']);
 * A(() => console.log($items.length)); // Subscribes to length
 * setTimeout(() => $items.push('c'), 2000); // Triggers the observing function
 * ```
 *
 * @example Primitive
 * ```javascript
 * const $name = A.proxy('Aberdeen');
 * A(() => console.log($name.value)); // Subscribes to value
 * setTimeout(() => $name.value = 'UI', 2000); // Triggers the observing function
 * ```
 *
 * @example Set
 * ```javascript
 * const $tags = A.proxy(new Set(['ui', 'tiny']));
 * A(() => console.log($tags.has('ui'), $tags.size));
 * setTimeout(() => $tags.add('fast'), 1000);
 * ```
 *
 * @example Class instance
 * ```typescript
 * class Widget {
 *   constructor(public name: string, public width: number, public height: number) {}
 *   grow() { this.width *= 2; }
 *   toString() { return `${this.name}Widget (${this.width}x${this.height})`; }
 * }
 * let $graph: Widget = A.proxy(new Widget('Graph', 200, 100));
 * A(() => console.log(''+$graph));
 * setTimeout(() => $graph.grow(), 2000);
 * setTimeout(() => $graph.grow(), 4000);
 * ```
 */
export function proxy(target: TargetType): TargetType {
	if (target instanceof Promise) {
		const result: PromiseProxy<any> = optProxy({
			busy: true,
		});
		target
			.then((value) => {
				result.value = value;
				result.busy = false;
			})
			.catch((err) => {
				result.error = err;
				result.busy = false;
			});
		return result;
	}
	return optProxy(
		typeof target === "object" && target !== null ? target : { value: target },
	);
}

/**
 * Returns the original, underlying data target from a reactive proxy created by {@link proxy}.
 * If the input `target` is not a proxy, it is returned directly.
 *
 * This is useful when you want to avoid triggering subscriptions during read operations or
 * re-executes during write operations. Using {@link peek} is an alternative way to achieve this.
 *
 * @param target - A proxied object, array, or any other value.
 * @returns The underlying (unproxied) data, or the input value if it wasn't a proxy.
 * @template T - The type of the target.
 *
 * @example
 * ```typescript
 * const $user = A.proxy({ name: 'Frank' });
 * const rawUser = A.unproxy($user);
 *
 * // Log reactively
 * A(() => console.log('proxied', $user.name));
 * // The following will only ever log once, as we're not subscribing to any observable
 * A(() => console.log('unproxied', rawUser.name));
 *
 * // This cause the first log to run again:
 * setTimeout(() => $user.name += '!', 1000);
 *
 * // This doesn't cause any new logs:
 * setTimeout(() => rawUser.name += '?', 2000);
 *
 * // Both $user and rawUser end up as `{name: 'Frank!?'}`
 * setTimeout(() => {
 *   console.log('final proxied', $user)
 *   console.log('final unproxied', rawUser)
 * }, 3000);
 * ```
 */
export function unproxy<T>(target: T): T {
	return target ? (target as any)[TARGET_SYMBOL] || target : target;
}

const onDestroyMap: WeakMap<Node, string | ((...args: any[]) => void) | true> =
	new WeakMap();

function destroyWithClass(element: Element, cls: string) {
	const classes = cls.split(".").filter((c) => c);
	element.classList.add(...classes);
	// Backstop, covering animations that never finish and engines without `getAnimations`.
	const timer = setTimeout(() => element.remove(), 3000);
	if (!element.getAnimations) return;
	// Defer to a microtask, so that destroying many elements at once triggers a single
	// style flush (by `getAnimations`) instead of one per element.
	queueMicrotask(() => {
		const remove = () => {
			clearTimeout(timer);
			element.remove();
		};
		// This sees the transitions/animations the class change set in motion, delay
		// phase and descendants included. If it started none (no transition defined,
		// or none can run because the element is hidden), remove right away.
		const animations = element.getAnimations({ subtree: true });
		if (animations.length) {
			Promise.allSettled(animations.map((a) => a.finished)).then(remove);
		} else {
			remove();
		}
	});
}

/**
 * Recursively copies properties or array items from `src` to `dst`.
 * It's designed to work efficiently with reactive proxies created by {@link proxy}.
 *
 * - **Minimizes Updates:** When copying between objects/arrays (proxied or not), if a nested object
 *   exists in `dst` with the same constructor as the corresponding object in `src`, `copy`
 *   will recursively copy properties into the existing `dst` object instead of replacing it.
 *   This minimizes change notifications for reactive (proxied) destinations.
 * - **Fast with Proxies:** When copying to/from proxied objects, `copy` uses Aberdeen internals
 *   to speed things up (compared to a non-Aberdeen-aware deep copy).
 *
 * @param dst - The destination object/array/Map (proxied or unproxied).
 * @param src - The source object/array/Map (proxied or unproxied). It won't be modified.
 * @template T - The type of the objects being copied.
 * @returns `true` if any changes were made to `dst`, or `false` if not.
 * @throws Error if attempting to copy an array into a non-array or vice versa.
 *
 * @example Basic Copy
 * ```typescript
 * const $source = A.proxy({ a: 1, b: { c: 2 } });
 * const $dest = A.proxy({ b: { d: 3 } });
 * A.copy($dest, $source);
 * console.log($dest); // proxy({ a: 1, b: { c: 2 } })
 * A.copy($dest, 'b', { e: 4 });
 * console.log($dest); // proxy({ a: 1, b: { e: 4 } })
 * ```
 */

export function copy<T extends object>(dst: T, src: T): boolean;
/**
 * Like above, but copies `src` into `dst[dstKey]`. This is useful if you're unsure if dst[dstKey]
 * already exists (as the right type of object) or if you don't want to subscribe to dst[dstKey].
 * 
 * @param dstKey - Optional key in `dst` to copy into. 
 */
export function copy<T extends object>(dst: T, dstKey: keyof T, src: T[typeof dstKey]): boolean;
export function copy(a: any, b: any, c?: any): boolean {
	if (arguments.length > 2) return copySet(a, b, c, 0);
	return copyImpl(a, b, 0);
}

function copySet(dst: any, dstKey: any, src: any, flags: number): boolean {
	let dstVal = peek(dst, dstKey);
	if (src === dstVal) return false;
	if (typeof dstVal === "object" && dstVal !== null && typeof src === "object" && src !== null && dstVal.constructor === src.constructor) {
		return copyImpl(dstVal, src, flags);
	}
	src = clone(src); 
	if (dst instanceof Map) dst.set(dstKey, src);
	else dst[dstKey] = clone(src);
	return true;
}

/**
 * Like {@link copy}, but uses merge semantics. Properties in `dst` not present in `src` are kept.
 * `null`/`undefined` in `src` delete properties in `dst`.
 * 
 * @example Basic merge
 * ```typescript
 * const source = { b: { c: 99 }, d: undefined }; // d: undefined will delete
 * const $dest = A.proxy({ a: 1, b: { x: 5 }, d: 4 });
 * A.merge($dest, source);
 * A.merge($dest, 'b', { y: 6 }); // merge into $dest.b
 * A.merge($dest, 'c', { z: 7 }); // $dest.c doesn't exist yet, so it will just be assigned
 * console.log($dest); // proxy({ a: 1, b: { c: 99, x: 5, y: 6 }, c: { z: 7 } })
 * ```
 *
 */
export function merge<T extends object>(dst: T, value: Partial<T>): boolean;
export function merge<T extends object>(dst: T, dstKey: keyof T, value: Partial<T[typeof dstKey]>): boolean;
export function merge(a: any, b: any, c?: any) {
	if (arguments.length > 2) return copySet(a, b, c, MERGE);
	return copyImpl(a, b, MERGE);
}

function copyImpl(dst: any, src: any, flags: number): boolean {
	// We never want to subscribe to reads we do to the target (to find changes). So we'll
	// take the unproxied version and `emit` updates ourselve.
	let unproxied = (dst as any)[TARGET_SYMBOL];
	if (unproxied) {
		dst = unproxied;
		flags |= COPY_EMIT;
	}
	// For performance, we'll work on the unproxied `src` and manually subscribe to changes.
	unproxied = (src as any)[TARGET_SYMBOL];
	if (unproxied) {
		src = unproxied;
		// If we're not in peek mode, we'll manually subscribe to all source reads.
		if (currentScope !== ROOT_SCOPE && !peeking) flags |= COPY_SUBSCRIBE;
	}

	return copyRecursive(dst, src, flags);
}

// The dst and src parameters must be objects. Will throw a friendly message if they're not both the same type.
function copyRecursive<T extends object>(dst: T, src: T, flags: number): boolean {

	if (flags & COPY_SUBSCRIBE) subscribe(src, ANY_SYMBOL);
	let changed = false;

	// The following loops are somewhat repetitive, but it keeps performance high by avoiding
	// function calls and extra checks within the loops.

	if (src instanceof Array && dst instanceof Array) {
		const dstLen = dst.length;
		const srcLen = src.length;
		for (let index = 0; index < srcLen; index++) {
			// changed = copyValue(dst, i, src[i], flags) || changed;

			let dstValue = dst[index];
			if (dstValue === undefined && !dst.hasOwnProperty(index)) dstValue = EMPTY;
			let srcValue = src[index];
			if (srcValue === undefined && !src.hasOwnProperty(index)) {
				delete dst[index];
				if (flags & COPY_EMIT) emit(dst, index, EMPTY, dstValue);
				changed = true;
			}
			else if (dstValue !== srcValue) {
				if (typeof srcValue === "object" && srcValue !== null) {
					if (typeof dstValue === "object" && dstValue !== null && srcValue.constructor === dstValue.constructor && !(OPAQUE in srcValue)) {
						changed = copyRecursive(dstValue, srcValue, flags) || changed;
						continue;
					}
					srcValue = cloneRecursive(srcValue, flags & COPY_SUBSCRIBE);
				}
				dst[index] = srcValue;

				if (flags & COPY_EMIT) emit(dst, index, srcValue, dstValue);
				changed = true;
			}
		}

		// Leaving additional values in the old array doesn't make sense, so we'll do this even when MERGE is set:
		if (srcLen !== dstLen) {
			if (flags & COPY_EMIT) {
				for (let i = srcLen; i < dstLen; i++) {
					const old = dst[i];
					delete dst[i];
					emit(dst, i, EMPTY, old);
				}
				dst.length = srcLen;
				emit(dst, "length", srcLen, dstLen);
			} else {
				dst.length = srcLen;
			}
			changed = true;
		}
	} else if (src instanceof Map && dst instanceof Map) {
		for (const key of src.keys()) {
			// changed = copyValue(dst, k, src.get(k), flags) || changed;
			let srcValue = src.get(key);
			let dstValue = dst.get(key);
			if (dstValue === undefined && !dst.has(key)) dstValue = EMPTY;
			if (dstValue !== srcValue) {
				if (typeof srcValue === "object" && srcValue !== null) {
					if (typeof dstValue === "object" && dstValue !== null && srcValue.constructor === dstValue.constructor && !(OPAQUE in srcValue)) {
						changed = copyRecursive(dstValue, srcValue, flags) || changed;
						continue;
					}
					srcValue = cloneRecursive(srcValue, flags & COPY_SUBSCRIBE);
				}

				dst.set(key, srcValue);

				if (flags & COPY_EMIT) emit(dst, key, srcValue, dstValue);
				changed = true;
			}
		}

		if (!(flags & MERGE)) {
			for (const k of dst.keys()) {
				if (!src.has(k)) {
					const old = dst.get(k);
					dst.delete(k);
					if (flags & COPY_EMIT) {
						emit(dst, k, EMPTY, old);
					}
					changed = true;
				}
			}
		}
	} else if (src.constructor === dst.constructor) {
		for (const key of Object.keys(src) as (keyof typeof src)[]) {
			let srcValue = src[key];
			const dstValue = dst.hasOwnProperty(key) ? dst[key] : EMPTY;
			if (dstValue !== srcValue) {
				if (typeof srcValue === "object" && srcValue !== null) {
					if (typeof dstValue === "object" && dstValue !== null && srcValue.constructor === dstValue.constructor && !(OPAQUE in srcValue)) {
						changed = copyRecursive(dstValue as typeof srcValue, srcValue, flags) || changed;
						continue;
					}
					srcValue = cloneRecursive(srcValue, flags & COPY_SUBSCRIBE);
				}

				dst[key] = srcValue;

				if (flags & COPY_EMIT) emit(dst, key, srcValue, dstValue);
				changed = true;
			}
		}

		if (!(flags & MERGE)) {
			for (const k of Object.keys(dst) as (keyof typeof dst)[]) {
				if (!src.hasOwnProperty(k)) {
					const old = dst[k];
					delete dst[k];
					if (flags & COPY_EMIT && old !== undefined) {
						emit(dst, k, EMPTY, old);
					}
					changed = true;
				}
			}
		}
	} else {
		throw new Error(`Incompatible or non-object types: ${src?.constructor?.name || typeof src} vs ${dst?.constructor?.name || typeof dst}`);
	}
	return changed;
}

const MERGE = 1;
const COPY_SUBSCRIBE = 32;
const COPY_EMIT = 64;

/**
 * A symbol that controls how Aberdeen handles an object in copy operations and proxy wrapping.
 *
 * The **presence** of this symbol (regardless of its value) prevents deep-copying: the object is
 * stored and passed by reference in {@link clone} and {@link copy}.
 *
 * The **value** of the symbol controls proxy wrapping when the object is read from reactive state:
 * - **Truthy** (e.g. `true`): the object is fully opaque — it is not wrapped in a proxy, so its
 *   properties are not observable. Use this for objects that break when proxied (e.g. class instances
 *   with internal slots, Promises) or that must be invisible to Aberdeen's reactive system.
 * - **Falsy** (e.g. `false`): the object is still wrapped in a proxy, so reads on its properties
 *   create reactive dependencies as normal — only deep-copying is suppressed.
 */
export const OPAQUE = Symbol("OPAQUE");

/**
 * Use {@link OPAQUE} instead. This is an alias kept for backward compatibility.
 * 
 * @deprecated
 */
export const NO_COPY = OPAQUE;

// Built-in types with 'internal slots' break when proxied. So we'll treat them
// as primitive values.
(Promise.prototype as any)[OPAQUE] = true;
(Date.prototype as any)[OPAQUE] = true;
(Node.prototype as any)[OPAQUE] = true;

// Same for Temporal types
declare const Temporal: any;
if (typeof Temporal !== 'undefined') {
	for(const name of 'Duration Instant PlainDate PlainDateTime PlainMonthDay PlainTime PlainYearMonth ZonedDateTime'.split(' ')) {
		const cls = Temporal[name];
		if (cls) cls.prototype[OPAQUE] = true;
	}
}

/**
 * A reactive object containing CSS variable definitions.
 *
 * Any property you assign to `cssVars` becomes available as a CSS custom property throughout your application.
 *
 * Use {@link setSpacingCssVars} to optionally initialize `cssVars[1]` through `cssVars[12]` with an exponential spacing scale.
 *
 * When you reference a CSS variable in Aberdeen using the `$` prefix (e.g., `$primary`), it automatically resolves to `var(--primary)`.
 * For numeric keys (which can't be used directly as CSS custom property names), Aberdeen prefixes them with `m` (e.g., `$3` becomes `var(--m3)`).
 *
 * When you add the first property to cssVars, Aberdeen automatically creates a reactive `<style>` tag in `<head>`
 * containing the `:root` CSS custom property declarations. The style tag is automatically removed if cssVars becomes empty.
 *
 * @example
 * ```javascript
 * import A from 'aberdeen';
 *
 * // Optionally initialize spacing scale
 * A.setSpacingCssVars(); // Uses defaults: base=1, unit='rem'
 *
 * // Define custom colors - style tag is automatically created
 * A.cssVars.primary = '#3b82f6';
 * A.cssVars.danger = '#ef4444';
 *
 * // Use in elements with the $ prefix
 * A('button bg:$primary fg:white #I'm a primary button');
 *
 * // Use spacing (if setSpacingCssVars() was called)
 * A('hr mt:$3'); // Sets margin-top to var(--m3)
 * ```
 */
export const cssVars: Record<string, string> = optProxy({});

/**
 * Initializes `cssVars[0]` through `cssVars[12]` with an exponential spacing scale.
 *
 * The scale is calculated as `2^(n-3) * base`, providing values from `0.25 * base` to `512 * base`.
 *
 * @param base - The base size for the spacing scale that will apply to `cssVars[3]`. Every step up the scale will double this, while every step down will halve it. Defaults to 1.
 * @param unit - The CSS unit to use, like 'rem', 'em', or 'px'. Defaults to 'rem'.
 *
 * @example
 * ```javascript
 * import A from 'aberdeen';
 * // Use default scale (0.25rem to 512rem)
 * A.setSpacingCssVars();
 *
 * // Use custom base size
 * A.setSpacingCssVars(16, 'px'); // 4px to 8192px
 *
 * // Use em units
 * A.setSpacingCssVars(1, 'em'); // 0.25em to 512em
 * 
 * // Show the last generated spacing values
 * A.onEach(A.cssVars, (value, key) => {
 * 	A(`div #${key} → ${value}`)
 * }, (value, key) => parseInt(key)); // Numeric sort
 * ```
 */
export function setSpacingCssVars(base = 1, unit = 'rem'): void {
	for (let i = 0; i <= 12; i++) {
		cssVars[i] = 2 ** (i - 3) * base + unit;
	}
}

// Matches: (1) url() content, (2) quoted content, (3) $varName at start or after space
const CSS_VAR_PATTERN = /(\burl\([^)]*\))|("[^"]*")|(^|[\s(,])\$([\w-]+)/g;
const DIGIT_FIRST = /^\d/;

/**
 * Expands all `$varName` patterns in a CSS value to `var(--varName)`.
 * Only matches `$` at the start of the value or after a space, `(` or `,`
 * (so e.g. `linear-gradient($a, $b)` expands as expected).
 * Content inside `url(...)` or quotes is preserved as-is.
 * Numeric names get an 'm' prefix (e.g., `$3` → `var(--m3)`).
 * Variable names may include dashes (e.g., `$primary-color` → `var(--primary-color)`).
 */
function cssVarRef(value: string): string {
	if (value.indexOf('$') < 0) return value;
	return value.replace(CSS_VAR_PATTERN, (match, parens, quoted, prefix, name) => {
		if (parens || quoted) return match;
		const varName = DIGIT_FIRST.test(name) ? `m${name}` : name;
		return `${prefix}var(--${varName})`;
	});
}

let darkModeState: {value: boolean} | undefined;

/**
 * Returns whether the user's browser prefers a dark color scheme.
 *
 * This function is reactive - scopes that call it will re-execute when the
 * browser's color scheme preference changes (via the `prefers-color-scheme` media query).
 *
 * Use this in combination with {@link A | A} and {@link cssVars} to implement theme switching:
 *
 * @returns `true` if the browser prefers dark mode, `false` if it prefers light mode.
 *
 * @example
 * ```javascript
 * import A from 'aberdeen';
 *
 * // Reactively set colors based on browser preference
 * A(() => {
 *   A.cssVars.bg = A.darkMode() ? '#1a1a1a' : '#ffffff';
 *   A.cssVars.fg = A.darkMode() ? '#e5e5e5' : '#000000';
 * });
 * 
 * A('div bg:$bg fg:$fg p:1rem #Colors change based on system dark mode preference');
 * ```
 */
export function darkMode(): boolean {
	if (!darkModeState) {
		// Initialize on first use

		if (typeof window === 'undefined' || !window.matchMedia) return false;
		const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
		
		darkModeState = proxy({ value: mediaQuery.matches });
		mediaQuery.addEventListener('change', () => darkModeState!.value = mediaQuery.matches);
	}

	return darkModeState.value;
}

// Simple recursive clone - no destination checking needed
function cloneRecursive<T extends object>(src: T, flags: number): T {
	if (OPAQUE in src) return src;
	if (flags & COPY_SUBSCRIBE) subscribe(src, ANY_SYMBOL);
	
	if (src instanceof Array) {
		return src.map(v => cloneValue(v, flags)) as T;
	}
	if (src instanceof Map) {
		const dst = new Map();
		for (const [k, v] of src) dst.set(k, cloneValue(v, flags));
		return dst as T;
	}
	const dst = Object.create(Object.getPrototypeOf(src));
	for (const k of Object.keys(src)) dst[k] = cloneValue((src as any)[k], flags);
	return dst;
}

function cloneValue(v: any, flags: number): any {
	return typeof v === "object" && v !== null ? cloneRecursive(v, flags) : v;
}

/**
 * Clone an (optionally proxied) object or array.
 *
 * @param src The object or array to clone. If it is proxied, `clone` will subscribe to any changes to the (nested) data structure.
 * @template T - The type of the objects being copied.
 * @returns A new unproxied array or object (of the same type as `src`), containing a deep copy of `src`.
 */
export function clone<T extends object>(src: T): T {
	if (typeof src !== 'object' || src === null) return src;
	let flags = 0;
	const unproxied = (src as any)[TARGET_SYMBOL];
	if (unproxied) {
		src = unproxied;
		if (currentScope !== ROOT_SCOPE && !peeking) flags = COPY_SUBSCRIBE;
	}
	return cloneRecursive(src, flags);
}

interface RefTarget {
	proxy: TargetType;
	index: any;
}
const refHandler: ProxyHandler<RefTarget> = {
	get(target: RefTarget, prop: any) {
		if (prop === TARGET_SYMBOL) {
			// Create a ref to the unproxied version of the target
			return ref(unproxy(target.proxy), target.index);
		}
		if (prop === "value") {
			return (target.proxy as any)[target.index];
		}
	},
	set(target: any, prop: any, value: any) {
		if (prop === "value") {
			(target.proxy as any)[target.index] = value;
			return true;
		}
		return false;
	},
};

/**
 * Creates a reactive reference (`{ value: T }`-like object) to a specific value
 * within a proxied object or array.
 *
 * This is primarily used for the `bind` property in {@link A | A} to create two-way data bindings
 * with form elements, and for passing a reactive property to any of the {@link A | A} key-value pairs.
 *
 * Reading `ref.value` accesses the property from the underlying proxy (and subscribes the current scope).
 * Assigning to `ref.value` updates the property in the underlying proxy (triggering reactive updates).
 *
 * @param target - The reactive proxy (created by {@link proxy}) containing the target property.
 * @param index - The key (for objects) or index (for arrays) of the property to reference.
 * @returns A reference object with a `value` property linked to the specified proxy property.
 *
 * @example
 * ```javascript
 * const $formData = A.proxy({ color: 'orange', velocity: 42 });
 *
 * // Usage with `bind`
 * A('input type=text bind=', A.ref($formData, 'color'));
 *
 * // Usage as a dynamic property, causes a TextNode with just the name to be created and live-updated
 * A('p text="Selected color: " text=', A.ref($formData, 'color'), 'color:', A.ref($formData, 'color'));
 *
 * // Changes are actually stored in $formData - this causes logs like `{color: "Blue", velocity 42}`
 * A(() => console.log($formData))
 * ```
 */
export function ref<T extends TargetType, K extends keyof T>(
	target: T,
	index: K,
): ValueRef<T[K]> {
	return new Proxy({ proxy: target, index }, refHandler) as any as ValueRef<
		T[K]
	>;
}

function applyBind(el: HTMLInputElement, target: any) {
	let onProxyChange: () => void;
	let onInputChange: () => void;
	const type = el.getAttribute("type");
	const value = unproxy(target).value;
	if (type === "checkbox") {
		if (value === undefined) target.value = el.checked;
		onProxyChange = () => {
			el.checked = target.value;
		};
		onInputChange = () => {
			target.value = el.checked;
		};
	} else if (type === "radio") {
		if (value === undefined && el.checked) target.value = el.value;
		onProxyChange = () => {
			el.checked = target.value === el.value;
		};
		onInputChange = () => {
			if (el.checked) target.value = el.value;
		};
	} else {
		onInputChange = () => {
			target.value = type === "number" || type === "range"
				? el.value === "" ? null : +el.value
				: el.value;
		};
		if (value === undefined) onInputChange();
		onProxyChange = () => {
			el.value = target.value;
			// biome-ignore lint/suspicious/noDoubleEquals: it's fine for numbers to be casts to strings here
			if (el.tagName === "SELECT" && el.value != target.value) {
				// Presumable, OPTIONs haven't been created yet. Try again after all currently queued work has been done.
				new DelayedOneTimeRunner(() => el.value = target.value);
			}
		};
	}
	derive(onProxyChange);
	el.addEventListener("input", onInputChange);
	clean(() => {
		el.removeEventListener("input", onInputChange);
	});
}

const RICH_PATTERN = /\*\*(.+?)\*\*|\*(.+?)\*|`(.+?)`|\[(.+?)\]\((.+?)\)/g;

const SPECIAL_PROPS: { [key: string]: (el: Element, value: any) => void } = {
	create: (el: Element, value: any) => {
		if (currentScope !== topRedrawScope) return;
		if (typeof value === "function") {
			value(el);
		} else {
			const classes = value.split(".").filter((c: any) => c);
			el.classList.add(...classes);
			(async () => {
				// attempt to prevent layout trashing
				(el as HTMLElement).offsetHeight; // trigger layout
				el.classList.remove(...classes);
			})();
		}
	},
	destroy: (el: Element, value: any) => {
		onDestroyMap.set(el, value);
	},
	html: (el: Element, value: any) => {
		if (el === currentScope.el && !el.firstChild && !currentScope.lastChild) {
			// Fast path: parse directly into the (empty) element. Register the
			// resulting nodes as scope children, so a redraw of the scope (whose
			// element may outlive it) removes them again instead of leaving them
			// behind and appending a duplicate.
			el.innerHTML = `${value}`;
			if (el.lastChild) currentScope.lastChild = el.lastChild;
		}
		else {
			// Slow path: create elements on a tmp parent, and then move them into place. The tmp
			// parent mirrors `el` (both tag name and namespace), as the parser interprets a fragment
			// relative to its context element: `<tr>` only survives inside a table, and SVG content
			// needs an SVG context to not become HTML elements.
			const tmpParent = el.namespaceURI === 'http://www.w3.org/2000/svg'
				? document.createElementNS('http://www.w3.org/2000/svg', el.tagName)
				: document.createElement(el.tagName);
			tmpParent.innerHTML = `${value}`;
			while (tmpParent.firstChild) addNode(el, tmpParent.firstChild);
		}
	},
	text: (el: Element, value: any) => {
		addNode(el, document.createTextNode(value));
	},
	rich: (el: Element, value: any) => {
		// Parse simple markdown: *italic*, **bold**, `code`, [text](url)
		let lastIndex = 0;
		let match: RegExpExecArray | null;
		const str = String(value);
		RICH_PATTERN.lastIndex = 0;
		while ((match = RICH_PATTERN.exec(str)) !== null) {
			if (match.index > lastIndex) {
				addNode(el, document.createTextNode(str.slice(lastIndex, match.index)));
			}
			let node: Node;
			if (match[1] !== undefined) {
				node = document.createElement("strong");
				node.textContent = match[1];
			} else if (match[2] !== undefined) {
				node = document.createElement("em");
				node.textContent = match[2];
			} else if (match[3] !== undefined) {
				node = document.createElement("code");
				node.textContent = match[3];
			} else {
				const a = document.createElement("a");
				a.textContent = match[4];
				a.href = match[5];
				node = a;
			}
			addNode(el, node);
			lastIndex = RICH_PATTERN.lastIndex;
		}
		if (lastIndex < str.length) {
			addNode(el, document.createTextNode(str.slice(lastIndex)));
		}
	},
};

/**
 * Make the `create` and `destroy` special properties no-ops.
 *
 * This is useful from within automated testing environments, where the transitioning
 * new and lingering old elements may make writing reliable selectors difficult.
 * 
 * As this is only intended for testing, there's no way to re-enable the special properties
 * once disabled.
 */
export function disableCreateDestroy() {
	SPECIAL_PROPS.create = SPECIAL_PROPS.destroy = () => {};
}

/**
 * The core function for building reactive user interfaces in Aberdeen. It creates and inserts new DOM elements
 * and sets attributes/properties/event listeners on DOM elements. It does so in a reactive way, meaning that
 * changes will be (mostly) undone when the current *scope* is destroyed or will be re-execute.
 *
 * @param {...(string | function | object | false | undefined | null)} args - Any number of arguments can be given. How they're interpreted depends on their types:
 *
 * ### String arguments
 * Strings can be used to create and insert new elements, set classnames for the *current* element, and add text to the current element.
 * The format of a string is: (**tag** | `.` **class** | **key**[=:]**val** | **key**[=:]"**val containing spaces**")* ('#' **text** | **key**[=:])?
 * 
 * So a string may consist of any number of...
 * - **tag** elements, like `h1` or `div`. These elements are created, added to the *current* element, and become the new *current* element for the rest of this `A` function execution.
 * - CSS classes prefixed by `.` characters. These classes will be added to the *current* element. Optionally, CSS classes can be appended to a **tag** without a space. So both `div.myclass` and `div .myclass` are valid and do the same thing.
 * - Property key/value pairs, like `type=password`, `placeholder="Your name"` or `data-id=123`. When the value contains spaces, it needs to be quoted with either "double quotes", 'single quotes' or \`backticks\`. Quotes within quoted values cannot be escaped (see the next rule for a solution). Key/value pairs will be handled according to *Property rules* below, but with the caveat that values can only be strings.
 * - CSS key/value pairs using two syntaxes:
 *   - **Short form** `key:value` (no space after colon): The value ends at the next whitespace. Example: `m:$3 bg:red r:8px`
 *   - **Long form** `key: value;` (space after colon): The value continues until a semicolon. Example: `box-shadow: 2px 0 6px black; transition: all 0.3s ease;`
 * 
 *   Both forms support CSS shortcuts (see below). You can mix them: `m:$3 box-shadow: 0 2px 4px rgba(0,0,0,0.2); bg:$cardBg`
 * The elements must be separated by spaces, except before a `.cssClass` if it is preceded by either **tag** or another CSS class.
 * 
 * And a string may end in...
 * - A '#' followed by text, which will be added as a `TextNode` to the *current* element. The text ranges til the end of the string, and may contain any characters, including spaces and quotes.
 * - A key followed by an '=' character, in which case the value is expected as a separate argument. The key/value pair is set according to the *Property rules* below. This is useful when the value is not a string or contains spaces or user data. Example: `A('button text="Click me" click=', () => alert('Clicked!'))` or `A('input.value=', someUserData, "placeholder=", "Type your stuff")`. In case the value is a proxied object, its `.value` property will be applied reactively without needing to rerender the parent scope.
 * - A key followed by a ':' character (with no value), in which case the value is expected as a separate argument. The value is treated as a CSS value to be set inline on the *current* element. Example: `A('div margin-top:', someValueInPx)`. In case the value is a proxied object, its `.value` property will be applied reactively without needing to rerender the parent scope.
 * 
 * ### Function arguments
 * When a function (without arguments nor a return value) is passed in, it will be reactively executed in its own observer scope, preserving the *current* element. So any `A()` invocations within this function will add child elements to or set properties on that element. If the function reads observable data, and that data is changed later on, the function we re-execute (after side effects, such as DOM modifications through `A`, have been cleaned - see also {@link clean}).
 * 
 * ### Object arguments
 * When an object is passed in, its key-value pairs are used to modify the *current* element according to the *Property rules* below, *unless* the key starts with a `$` character, in which case that character is stripped of and the key/value pair is treated as a CSS property, subject to the *CSS shortcuts* below. In case a value is a proxied object, its `.value` property will be applied reactively without needing to rerender the parent scope. In most cases, the string notation (`key=` and `key:`) is preferred over this object notation, for readability.
 * 
 * ### DOM node arguments
 * When a DOM Node (Element or TextNode) is passed in, it is added as a child to the *current* element. If the Node is an Element, it becomes the new *current* element for the rest of this `A` function execution.
 * 
 * ### Property rules
 * - **Attribute:** The common case is setting the value as an HTML attribute named key. For example `A('input placeholder=Name')` results in `<input placeholder="Name">`.
 * - **Event listener:** If the value is a `function` it is set as an event listener for the event with the name given by the key. For example: A('button text=Press! click=', () => alert('Clicked!'))`. The event listener will be removed when the current scope is destroyed.
 * - **DOM property:** When the value is a boolean, or the key is `"value"` or `"selectedIndex"`, it is set on the `current` element as a DOM property instead of an HTML attribute. For example `A('checked=', true)` would do `el.checked = true` for the *current* element.
 * - **Conditional CSS class:** If the key starts with a `.` character, its either added to or removed from the *current* element as a CSS class, based on the truthiness of the value. So `A('.hidden=', isHidden)` would toggle the `hidden` CSS class. This only works if the `=` is the last character of the string, and the next argument is the value. Its common for the value to be a proxied object, in which case its `.value` is reactively applied without needing to rerender the parent scope.
 * - **Create transition:** When the key is `"create"`, the value will be added as a CSS class to the *current* element immediately, and then removed right after the browser has finished doing a layout pass. This behavior only triggers when the scope setting the `create` is the top-level scope being (re-)run. This allows for creation transitions, without triggering the transitions for deeply nested elements being drawn as part of a larger component. The string may also contain multiple dot-separated CSS classes, such as `.fade.grow`. The initial dot is optional. Alternatively, to allow for more complex transitions, the value may be a function that receives the `HTMLElement` being created as its only argument. It is *only* called if this is the top-level element being created in this scope run. See `transitions.ts` in the Aberdeen source code for some examples.
 * - **Destroy transition:** When the key is `"destroy"` the value will be used to apply a CSS transition if the *current* element is later on removed from the DOM and is the top-level element to be removed. This happens as follows: the value string is added as a CSS class to the element, allowing for a deletion transition, and the element is actually removed from the DOM once the transitions/animations this started (anywhere in its subtree) have finished — immediately if there are none, and after at most 3 seconds in any case. The string may also contain multiple dot-separated CSS classes, such as `.fade.shrink`. The initial dot is optional. Alternatively, to allow for more complex transitions, the value may be a function that receives the `HTMLElement` to be removed from the DOM as its only argument. This function may perform any transitions and is then itself responsible for eventually removing the element from the DOM. See `transitions.ts` in the Aberdeen source code for some examples.
 * - **Two-way data binding:** When the key is `"bind"` a two-way binding between the `.value` property of the given proxied object, and the *current* input element (`<input>`, `<select>` or `<textarea>`) is created. This is often used together with {@link ref}, in order to use properties other than `.value`.
 * - **Text:**: If the key is `"text"`, the value will be appended as a `TextNode` to the *current* element. The same can also be done with the `#` syntax in string arguments, though `text=` allows additional properties to come after in the same string: `A('button text=Hello click=', alert)`.
 * - **Unsafe HTML:** When the key is `"html"`, the value will be added as HTML to the *current* element. This should only be used in exceptional situations. Beware of XSS! Never use this with untrusted user data.
 * - **Rich text:** When the key is `"rich"`, the value is parsed as simple markdown-like syntax and rendered as inline elements. Supports `*italic*`, `**bold**`, `` `code` ``, and `[link text](/path)`. All text content is safely escaped, making it suitable for user data (though links should be validated if untrusted). Example: `A('p rich="Click *here* for **more** info")`.
 * 
 * ### CSS shortcuts
 * For conciseness, Aberdeen supports some CSS shortcuts when setting CSS properties.
 * | Shortcut | Expands to |
 * |----------|------------|
 * | `m`, `mt`, `mb`, `ml`, `mr` | `margin`, `margin-top`, `margin-bottom`, `margin-left`, `margin-right` |
 * | `mv`, `mh` | Vertical (top+bottom) or horizontal (left+right) margins |
 * | `p`, `pt`, `pb`, `pl`, `pr` | `padding`, `padding-top`, `padding-bottom`, `padding-left`, `padding-right` |
 * | `pv`, `ph` | Vertical or horizontal padding |
 * | `w`, `h` | `width`, `height` |
 * | `bg` | `background` |
 * | `fg` | `color` |
 * | `r` | `border-radius` |
 * 
 * Also, when the value is a string starting with `$`, it is treated as a reference to a CSS variable, expanding to `var(--variableName)`. For numeric variable names (which can't be used directly as CSS custom property names), Aberdeen prefixes them with `m`, so `$3` expands to `var(--m3)`. This is primarily intended for use with {@link setSpacingCssVars}, which initializes spacing variables named `0` through `12` with an exponential spacing scale.
 *
 * To *set* a CSS custom property inline on an element, use a `--name` or (symmetrically with the `$`-reference syntax above) a `$name` key. For example `A('div --primary:red')` and `A('div $primary:red')` both set `--primary` to `red`.
 * 
 * @returns The most inner DOM element that was created (not counting text nodes nor elements created by content functions), or the current element if no new element was created. You should normally not need to use the return value - use this function's DOM manipulation abilities instead. One valid use case is when integrating with non-Aberdeen code that requires a reference to a DOM element.
 *
 * @example Create Element
 * ```typescript
 * A('button.secondary.outline text=Submit color:red disabled=', false, 'click=', () => console.log('Clicked!'));
 * ```
 * 
 * We want to set `disabled` as a property instead of an attribute, so we must use the `key=` syntax in order to provide
 * `false` as a boolean instead of a string.
 *
 * @example Create Nested Elements
 * ```typescript
 * let inputElement: Element = A('label text="Click me" input type=checkbox');
 * // You should usually not touch raw DOM elements, unless when integrating
 * // with non-Aberdeen code.
 * console.log('DOM element:', inputElement);
 * ```
 *
 * @example Content Functions & Reactive Scope
 * ```typescript
 * const $state = A.proxy({ count: 0 });
 * A('div', () => { // Outer element
 *   // This scope re-renders when $state.count changes
 *   A(`p#Count is ${$state.count}`);
 *   A('button text=Increment click=', () => $state.count++);
 * });
 * ```
 *
 * @example Two-way Binding
 * ```typescript
 * const $user = A.proxy({ name: '' });
 * A('input placeholder=Name bind=', A.ref($user, 'name'));
 * A('h3', () => { // Reactive scope
 *   A(`#Hello ${$user.name || 'stranger'}`);
 * });
 * ```
 *
 * @example Conditional Rendering
 * ```typescript
 * const $show = A.proxy(false);
 * A('button click=', () => $show.value = !$show.value, () => A($show.value ? '#Hide' : '#Show'));
 * A(() => { // Reactive scope
 *   if ($show.value) {
 *     A('p#Details are visible!');
 *   }
 * });
 * ```
 * 
 * @example Proxied objects as values
 * ```typescript
 * const $myColor = A.proxy('red');
 * A('p text="The color is " text=', $myColor, 'click=', () => $myColor.value = 'yellow')
 * // Clicking the text will cause it to change color without recreating the <p> itself
 * ```
 * This is often used together with {@link ref}, in order to use properties other than `.value`.
 */

export function A(...args: any[]): undefined | Element {
	let el: undefined | Element = currentScope.el;
	let svg: boolean = currentScope.svg

	const argCount = args.length;
	for(let argIndex = 0; argIndex < argCount; argIndex++) {
		const arg = args[argIndex];
		if (arg == null || arg === false) {
			// Ignore
		} else if (typeof arg === "string") {
			let argLen = arg.length;
			let nextPos = 0;
			for(let pos=0; pos<argLen; pos=nextPos+1) {
				nextPos = findFirst(arg, " .=:#", pos);
				const next = arg[nextPos];

				if (next === ":") {
					// Style property: key:value or key: value;
					const key = '$' + arg.substring(pos, nextPos);
					if (nextPos + 1 >= argLen) {
						applyArg(el, key, args[++argIndex]);
						break;
					}
					if (arg[nextPos + 1] === ' ') {
						// Long form: "key: value;" - read until semicolon
						const endIndex = findFirst(arg, ";", nextPos + 2);
						const value = arg.substring(nextPos + 2, endIndex).trim();
						applyArg(el, key, value);
						nextPos = endIndex;
					} else {
						// Short form: "key:value" - read until whitespace
						const endIndex = findFirst(arg, " ", nextPos + 1);
						const value = arg.substring(nextPos + 1, endIndex);
						applyArg(el, key, value);
						nextPos = endIndex;
					}
				} else if (next === "=") {
					// Attribute: key=value or key="quoted value"
					const key = arg.substring(pos, nextPos);
					if (nextPos + 1 >= argLen) {
						applyArg(el, key, args[++argIndex]);
						break;
					}
					const afterEquals = arg[nextPos + 1];
					if (afterEquals === '"' || afterEquals === "'" || afterEquals === "`") {
						const endIndex = findFirst(arg, afterEquals, nextPos + 2);
						const value = arg.substring(nextPos + 2, endIndex);
						applyArg(el, key, value);
						nextPos = endIndex;
					} else {
						const endIndex = findFirst(arg, " ", nextPos + 1);
						const value = arg.substring(nextPos + 1, endIndex);
						applyArg(el, key, value);
						nextPos = endIndex;
					}
				} else {
					if (nextPos > pos) { // Up til this point if non-empty, is a tag
						const tag = arg.substring(pos, nextPos);
						// Determine which namespace to use for element creation
						svg ||= tag === 'svg';
						let newEl = svg ? document.createElementNS('http://www.w3.org/2000/svg', tag) : document.createElement(tag);
						addNode(el, newEl);
						el = newEl;
					}

					if (next === "#") { // The rest of the string is text (or a text arg follows)	
						const text = nextPos + 1 < argLen ? arg.substring(nextPos + 1) : args[++argIndex];
						applyArg(el, "text", text);
						break;
					}

					if (next === ".") { // Class name
						let classEnd = findFirst(arg, " #=.", nextPos + 1);
						if (arg[classEnd] === '=' && classEnd + 1 >= argLen) {
							// Conditional class name. Pass to applyArg including the leading '.'
							applyArg(el, arg.substring(nextPos, classEnd), args[++argIndex]);
							nextPos = classEnd;
						} else {
							// An unconditional class name
							let className: any = arg.substring(nextPos + 1, classEnd);
							const cls = className || args[++argIndex];
							// Only undo on clean if we actually added it (don't clobber a pre-existing class).
							if (!el.classList.contains(cls)) {
								if (el === currentScope.el) recordSideEffect(currentScope, SideEffect.Class, cls, false);
								el.classList.add(cls);
							}
							nextPos = classEnd - 1;
						}
					}
				}
			}
		} else if (typeof arg === "object") {
			if (arg.constructor !== Object) {
				if (arg instanceof Node) {
					addNode(el, arg);
					if (arg instanceof Element) {
						el = arg;
						svg = arg.namespaceURI === 'http://www.w3.org/2000/svg';
					}
				} else {
					throw new Error(`Unexpected argument: ${arg}`);
				}
			} else {
				for (const key of Object.keys(arg)) {
					applyArg(el, key, arg[key]);
				}
			}
		} else if (typeof arg === "function") {
			new RegularScope(el, svg, arg);
		} else {
			throw new Error(`Unexpected argument: ${arg}`);
		}
	}
	return el;
}

function findFirst(str: string, chars: string, startPos: number): number {
	if (chars.length === 1) {
		const idx = str.indexOf(chars, startPos);
		return idx >= 0 ? idx : str.length;
	}
	const strLen = str.length;
	for (let i = startPos; i < strLen; i++) {
		if (chars.indexOf(str[i]) >= 0) return i;
	}
	return strLen;
}

let cssCount = 0;

/**
 * Inserts CSS rules into the document, scoping them with a unique class name.
 *
 * The `style` parameter can be either:
 * - A **concise style string** (for rules applying to the root class).
 * - An **object** where keys are selectors (with `&` representing the root class) 
 *   and values are concise style strings or nested objects. When the key does not contain `&`,
 *   it is treated as a descendant selector. So `{p: "color:red"}` becomes `".AbdStlX p { color: red; }"` with `AbdStlX` being the generated class name.
 *
 * ### Concise Style Strings
 * 
 * Concise style strings use two syntaxes (same as inline CSS in {@link A | A}):
 * - **Short form** `key:value` (no space after colon): The value ends at the next whitespace.
 *   Example: `'m:$3 bg:red r:8px'`
 * - **Long form** `key: value;` (space after colon): The value continues until a semicolon.
 *   Example: `'box-shadow: 2px 0 6px black; transition: all 0.3s ease;'`
 * 
 * Both forms can be mixed: `'m:$3 box-shadow: 0 2px 4px rgba(0,0,0,0.2); bg:$cardBg'`
 * 
 * Supports the same CSS shortcuts as {@link A | A} and CSS variable references with `$` (e.g., `$primary`, `$3`).
 * 
 * CSS is inserted into the <head> in an order relative to other insert(Global)Css items that is consistent
 * based on when the containing Aberdeen scope was first defined. This allows changing styles without changing
 * order-based precedence.
 *
 * @param style - A concise style string or a style object.
 * @returns The unique class name prefix used for scoping (e.g., `.AbdStl1`). 
 *          Use this prefix with {@link A | A} to apply the styles.
 *
 * @example Basic Usage with Shortcuts and CSS Variables
 * ```typescript
 * const cardClass = A.insertCss({
 *   '&': 'bg:white p:$4 r:8px transition: background-color 0.3s;',
 *   '&:hover': 'bg:#f5f5f5',
 * });
 *
 * A('section', cardClass, () => { 
 *   A('p#Card content'); 
 * });
 * ```
 *
 * @example Nested Selectors and Media Queries
 * ```typescript
 * const formClass = A.insertCss({
 *   '&': 'bg:#0004 p:$3 r:$2',
 *   button: {
 *     '&': 'bg:$primary fg:white p:$2 r:4px cursor:pointer',
 *     '&:hover': 'bg:$primaryHover',
 *     '&:disabled': 'bg:#ccc cursor:not-allowed',
 *     '.icon': 'display:inline-block mr:$1',
 *     '@media (max-width: 600px)': 'p:$1 font-size:14px'
 *   }
 * });
 *
 * A('form', formClass, () => {
 *   A('button', () => {
 *     A('span.icon text=🔥');
 *     A('#Click Me');
 *   });
 * });
 * ```
 *
 * @example Complex CSS Values
 * ```typescript
 * const badge = A.insertCss({
 *   '&::before': 'content: "★"; color:gold mr:$1',
 *   '&': 'position:relative box-shadow: 0 2px 8px rgba(0,0,0,0.15);'
 * });
 *
 * A(badge + ' span#Product Name');
 * ```
 */
export function insertCss(style: string | object): string {
	const prefix = `.AbdStl${++cssCount}`;
	const css = typeof style === 'string' ? styleStringToCss(style, prefix) : objectToCss(style, prefix);
	if (css) {
		const cnt = cssSnippetCount++;
		const key = arrayToStr([currentScope.prio, cnt]);
		cssSnippets[key] = css;
		clean(() => delete cssSnippets[key]);
	}
	return prefix;
}

/**
 * Inserts CSS rules globally (unscoped).
 * 
 * Works exactly like {@link insertCss}, but without prefixing selectors with a unique class name.
 * This is useful for global resets, base styles, or styles that need to apply to the entire document.
 * 
 * Accepts the same concise style string syntax and CSS shortcuts as {@link insertCss}.
 * See {@link insertCss} for detailed documentation on syntax and shortcuts.
 * 
 * @param style - Object with selectors as keys and concise CSS strings as values.
 * 
 * CSS is inserted into the <head> in an order relative to other insert(Global)Css items that is consistent
 * based on when the containing Aberdeen scope was first defined. This allows changing styles without changing
 * order-based precedence.
 * 
 * @example Global Reset and Base Styles
 * ```typescript
 * // Set up global styles using CSS shortcuts
 * A.insertGlobalCss({
 *   "*": "m:0 p:0 box-sizing:border-box",
 *   "body": "font-family: system-ui, sans-serif; m:0 p:$3 bg:#434 fg:#d0dafa",
 *   "a": "text-decoration:none fg:#57f",
 *   "a:hover": "text-decoration:underline",
 *   "code": "font-family:monospace bg:#222 fg:#afc p:4px r:3px"
 * });
 *
 * A('h2#Title without margins');
 * A('a#This is a link');
 * A('code#const x = 42;');
 * ```
 *
 * @example Responsive Global Styles
 * ```typescript
 * A.insertGlobalCss({
 *   "html": "font-size:16px",
 *   "body": "line-height:1.6",
 *   "h1, h2, h3": "font-weight:600 mt:$4 mb:$2",
 *   "@media (max-width: 768px)": {
 *     "html": "font-size:14px",
 *     "body": "p:$2"
 *   },
 *   "@media (prefers-color-scheme: dark)": {
 *     "body": "bg:#1a1a1a fg:#e5e5e5",
 *     "code": "bg:#2a2a2a"
 *   }
 * });
 * ```
 * At-rules such as `@media` and `@keyframes` should use nested objects. For keyframes,
 * the step selectors (`0%`, `50%`, `100%`, etc.) become the nested keys and each value
 * should be a concise CSS declaration string.
 *
 * @example Animation Keyframes
 * ```typescript
 * A.insertGlobalCss({
 *   "@keyframes connection-pulse": {
 *     "0%": "box-shadow: inset 0 0 0 0 rgba(255, 70, 70, 0.4);",
 *     "50%": "box-shadow: inset 0 0 0 6px rgba(255, 70, 70, 0.08);",
 *     "100%": "box-shadow: inset 0 0 0 0 rgba(255, 70, 70, 0.4);"
 *   }
 * });
 * ```
 */
export function insertGlobalCss(style: object) {
	const css = objectToCss(style, "");
	if (css) {
		const cnt = cssSnippetCount++;
		const key = arrayToStr([currentScope.prio, cnt]);
		cssSnippets[key] = css;
		clean(() => delete cssSnippets[key]);
	}
}

let cssSnippets = proxy({} as Record<string, string>);
let cssSnippetCount = 0;

function combinePrefixSelector(prefix: string, key: string): string {
	const sel = [];
	for(const p of prefix.split(',')) {
		for(const k of key.split(',')) {
			sel.push(k.includes("&") ? k.trim().replace(/&/g, p) : `${p} ${k.trim()}`.trim());
		}
	}
	return sel.join(',');
}

function objectToCss(style: object, prefix: string): string {
	let css = "";
	
	for (const [key, val] of Object.entries(style)) {
		if (val && typeof val === 'object') {
			// Nested object for media queries or compound selectors
			if (key.startsWith("@")) {
				// Media query or @ rule - nest the content
				css += `${key}{\n${objectToCss(val, prefix)}}\n`;
			} else {
				// Regular nested selector
				css += objectToCss(val, combinePrefixSelector(prefix, key));
			}
		} else if (typeof val === 'string') {			
			if (key.startsWith("@")) {
				// Media query with string value - wrap it
				css += `${key}{\n${styleStringToCss(val, prefix)}}\n`;
			} else {
				// String value - parse as style string
				css += styleStringToCss(val, combinePrefixSelector(prefix, key));
			}
		}
	}
	
	return css;
}


const KEBAB_SEGMENT = /-([a-z])/g;
function toCamel(p: string) {
	return p.replace(KEBAB_SEGMENT, (_, l) => l.toUpperCase());
}
const VALID_CSS_KEY = /^[a-zA-Z-]+$/;

function styleStringToCss(styleStr: string, selector: string): string {
	let props = "";
	
	for (let pos = 0, len = styleStr.length; pos < len;) {
		while (styleStr[pos] === ' ') pos++; // Skip whitespace
		if (pos >= len) break;
		
		const colon = styleStr.indexOf(':', pos);
		if (colon === -1) throw new Error(`Trailing data in style string: "${styleStr.substring(pos)}"`);
		const key = styleStr.substring(pos, colon);
		if (!VALID_CSS_KEY.test(key)) throw new Error(`Invalid CSS key: "${key}" in style string: "${styleStr}"`);
		pos = colon + 1;
		
		// Parse value based on whether there's a space after the colon
		let val: string;
		if (styleStr[pos] === ' ') {
			// Long form: space after colon means value ends at semicolon
			pos++; // skip the space
			const semi = styleStr.indexOf(';', pos);
			val = styleStr.substring(pos, semi === -1 ? len : semi).trim();
			pos = semi === -1 ? len : semi + 1;
		} else {
			// Short form: no space means value ends at whitespace
			const space = styleStr.indexOf(' ', pos);
			val = styleStr.substring(pos, space === -1 ? len : space);
			pos = space === -1 ? len : space;
		}
		
		// Expand shortcuts and add to props
		const v = cssVarRef(val);
		const exp = CSS_SHORT[key] || key;
		props += typeof exp === 'string' ? `${exp}:${v};` : exp.map(p => `${p}:${v};`).join('');
	}
	
	return props ? `${selector}{${props}}\n` : "";
}

const CSS_SHORT: Record<string, string | string[]> = {
	m: "margin",
	mt: "margin-top",
	mb: "margin-bottom",
	ml: "margin-left",
	mr: "margin-right",
	mh: ["margin-left", "margin-right"],
	mv: ["margin-top", "margin-bottom"],
	p: "padding",
	pt: "padding-top",
	pb: "padding-bottom",
	pl: "padding-left",
	pr: "padding-right",
	ph: ["padding-left", "padding-right"],
	pv: ["padding-top", "padding-bottom"],
	w: "width",
	h: "height",
	bg: "background",
	fg: "color",
	r: "border-radius",
};

function applyArg(el: Element, key: string, value: any) {
	if (typeof value === "object" && value !== null && value[TARGET_SYMBOL]) {
		// Value is a proxy
		if (key === "bind") {
			applyBind(el as HTMLInputElement, value);
		} else {
			new SetArgScope(el, key, value);
			// SetArgScope will (repeatedly) call `applyArg` again with the actual value
		}
	} else if (key[0] === ".") {
		// CSS class(es)
		const classes = key.substring(1).split(".");
		const list = el.classList;
		const desired = !!value;
		if (el === currentScope.el) {
			// Record each class's pre-scope presence so it can be restored when the scope is cleaned.
			for (const cls of classes) {
				const had = list.contains(cls);
				if (had !== desired) recordSideEffect(currentScope, SideEffect.Class, cls, had);
			}
		}
		if (desired) list.add(...classes);
		else list.remove(...classes);
	} else if (key[0] === "$") {
		// Style (with shortcuts)
		key = key.substring(1);
		// A leading `$` denotes a custom property, for symmetry with `$var` value references
		// (e.g. `$$primary: red` sets `--primary`). `--primary` works too.
		if (key[0] === "$") key = "--" + key.substring(1);
		const val = value == null || value === false ? "" : typeof value === 'string' ? cssVarRef(value) : String(value);
		const expanded = CSS_SHORT[key] || key;
		const style = (el as any).style;
		const setOwn = el === currentScope.el;
		const props = typeof expanded === "string" ? [expanded] : expanded;
		for (const prop of props) {
			if (prop[0] === "-" && prop[1] === "-") {
				// Custom property: must go through setProperty/removeProperty, as bracket
				// assignment of `--*` names is a no-op on a real CSSStyleDeclaration.
				if (setOwn) recordSideEffect(currentScope, SideEffect.Style, prop, style.getPropertyValue(prop));
				if (val === "") style.removeProperty(prop);
				else style.setProperty(prop, val);
			} else {
				const cm = toCamel(prop);
				// Record the style property's pre-scope value so it can be restored when the scope is cleaned.
				if (setOwn) recordSideEffect(currentScope, SideEffect.Style, cm, style[cm]);
				style[cm] = val;
			}
		}
	} else if (value == null) {
		// Value left empty
		// Do nothing
	} else if (key in SPECIAL_PROPS) {
		// Special property
		SPECIAL_PROPS[key](el, value);
	} else if (typeof value === "function") {
		// Event listener
		el.addEventListener(key, value);
		if (el === currentScope.el) recordSideEffect(currentScope, SideEffect.Event, key, value);
	} else if (
		value === true ||
		value === false ||
		key === "value" ||
		key === "selectedIndex"
	) {
		// DOM property
		if (el === currentScope.el) recordSideEffect(currentScope, SideEffect.Prop, key, (el as any)[key]);
		(el as any)[key] = value;
	} else {
		// HTML attribute
		if (el === currentScope.el) recordSideEffect(currentScope, SideEffect.Attr, key, el.getAttribute(key));
		el.setAttribute(key, value);
	}
}

function defaultOnError(error: Error) {
	console.error("Error while in Aberdeen render:", error);
	return true;
}
let onError: (error: Error) => boolean | undefined = defaultOnError;

/**
 * Sets a custom error handler function for errors that occur asynchronously
 * within reactive scopes (e.g., during updates triggered by proxy changes in
 * {@link derive} or {@link A | A} render functions).
 *
 * The default handler logs the error to `console.error` and adds a simple
 * 'Error' message div to the DOM at the location where the error occurred (if possible).
 *
 * Your handler can provide custom logging, UI feedback, or suppress the default
 * error message.
 *
 * @param handler - A function that accepts the `Error` object.
 *   - Return `false` to prevent adding an error message to the DOM.
 *   - Return `true` or `undefined` (or throw) to allow the error messages to be added to the DOM.
 *
 * @example Custom Logging and Suppressing Default Message
 * ```typescript
 * A.setErrorHandler(error => {
 *   console.warn('Aberdeen render error:', error.message);
 *   // Log to error reporting service
 *   // myErrorReporter.log(error);
 *
 *   try {
 *     // Attempt to show a custom message in the UI
 *     A('div#Oops, something went wrong!', errorClass);
 *   } catch (e) {
 *     // Ignore errors during error handling itself
 *   }
 *
 *   return false; // Suppress default console log and DOM error message
 * });
 *
 * // Styling for our custom error message
 * const errorClass = A.insertCss('background-color:#e31f00 display:inline-block color:white r:3px padding: 2px 4px;');
 *
 * // Cause an error within a render scope.
 * A('div.box', () => {
 *   // Will cause our error handler to insert an error message within the box
 *   noSuchFunction();
 * })
 * ```
 */
export function setErrorHandler(
	handler?: (error: Error) => boolean | undefined,
) {
	onError = handler || defaultOnError;
}

/**
 * Registers a cleanup function to be executed just before the current reactive scope
 * is destroyed or redraws.
 *
 * This is useful for releasing resources, removing manual event listeners, or cleaning up
 * side effects associated with the scope. Cleaners are run in reverse order of registration.
 *
 * Scopes are created by functions like {@link derive}, {@link mount}, {@link A | A} (when given a render function),
 * and internally by constructs like {@link onEach}.
 *
 * @param cleaner - The function to execute during cleanup.
 *
 * @example Maintaing a sum for a changing array
 * ```typescript
 * const $numbers = A.proxy([3, 5, 10]);
 * let $sum = A.proxy(0);
 *
 * // Show the array items and maintain the sum
 * A.onEach($numbers, (item, index) => {
 *     A(`code#${index}→${item}`);
 *     // We'll update $sum.value using peek, as += first does a read, but
 *     // we don't want to subscribe.
 *     A.peek(() => $sum.value += item);
 *     // Clean gets called before each rerun for a certain item index
 *     // No need for peek here, as the clean code doesn't run in an
 *     // observer scope.
 *     A.clean(() => $sum.value -= item);
 * })
 *
 * // Show the sum
 * A('h1 text=', $sum);
 *
 * // Make random changes to the array
 * const rnd = () => 0|(Math.random()*20);
 * setInterval(() => $numbers[rnd()] = rnd(), 1000);
 * ```
 */

export function clean(cleaner: () => void) {
	currentScope.cleaners.push(cleaner);
}

/**
 * Creates a reactive scope that automatically re-executes the provided function
 * whenever any proxied data (created by {@link proxy}) read during its last execution changes, storing
 * its return value in an observable.
 *
 * Updates are batched and run asynchronously shortly after the changes occur.
 * Use {@link clean} to register cleanup logic for the scope.
 * Use {@link peek} or {@link unproxy} within the function to read proxied data without subscribing to it.
 *
 * @param func - The function to execute reactively. Any DOM manipulations should typically
 *   be done using {@link A | A} within this function. Its return value will be made available as an
 *   observable returned by the `derive()` function.
 * @returns An observable object, with its `value` property containing whatever the last run of `func` returned.
 *
 * @example Observation creating UI components
 * ```typescript
 * const $data = A.proxy({ user: 'Frank', notifications: 42 });
 *
 * A('main', () => {
 *   console.log('Welcome');
 *   A('h3#Welcome, ' + $data.user); // Reactive text
 *
 *   A.derive(() => {
 *     // When $data.notifications changes, only this inner scope reruns,
 *     // leaving the `<p>Welcome, ..</p>` untouched.
 *     console.log('Notifications');
 *     A('code.notification-badge text=', $data.notifications);
 *     A('a text=Notify! click=', () => $data.notifications++);
 *   });
 * });
 * ```
 *
 * ***Note*** that the above could just as easily be done using `A(func)` instead of `derive(func)`.
 *
 * @example Observation with return value
 * ```typescript
 * const $counter = A.proxy(0);
 * setInterval(() => $counter.value++, 1000);
 * const $double = A.derive(() => $counter.value * 2);
 *
 * A('h3', () => {
 *     A(`#counter=${$counter.value} double=${$double.value}`);
 * })
 * ```
 *
 * @overload
 * @param func Func without a return value.
 */
export function derive<T>(func: () => T): ValueRef<T> {
	return new ResultScope<T>(func).result;
}

/**
 * Attaches a reactive Aberdeen UI fragment to an existing DOM element. Without the use of
 * this function, {@link A | A} will assume `document.body` as its root.
 *
 * It creates a top-level reactive scope associated with the `parentElement`. The provided
 * function `func` is executed immediately within this scope. Any proxied data read by `func`
 * will cause it to re-execute when the data changes, updating the DOM elements created within it.
 *
 * Calls to {@link A | A} inside `func` will append nodes to `parentElement`.
 * You can nest {@link derive} or other {@link A | A} scopes within `func`.
 * Use {@link unmountAll} to clean up all mounted scopes and their DOM nodes.
 *
 * Mounting scopes happens reactively, meaning that if this function is called from within another
 * ({@link derive} or {@link A | A} or {@link mount}) scope that gets cleaned up, so will the mount.
 *
 * @param parentElement - The native DOM `Element` to which the UI fragment will be appended.
 * @param func - The function that defines the UI fragment, typically containing calls to {@link A | A}.
 *
 * @example Basic Mount
 * ```javascript
 * // Create a pre-existing DOM structure (without Aberdeen)
 * document.body.innerHTML = `<h3>Static content <span id="title-extra"></span></h3><div class="box" id="app-root"></div>`;
 *
 * import A from 'aberdeen';
 *
 * const $runTime = A.proxy(0);
 * setInterval(() => $runTime.value++, 1000);
 *
 * A.mount(document.getElementById('app-root'), () => {
 *   A('h4#Aberdeen App');
 *   A(`p#Run time: ${$runTime.value}s`);
 *   // Conditionally render some content somewhere else in the static page
 *   if ($runTime.value&1) {
 *     A.mount(document.getElementById('title-extra'), () =>
 *       A(`i#(${$runTime.value}s)`)
 *     );
 *   }
 * });
 * ```
 *
 * Note how the inner mount behaves reactively as well, automatically unmounting when it's parent observer scope re-runs.
 */

export function mount(parentElement: Element, func: () => void) {
	new MountScope(parentElement, func);
}

/**
 * Removes all Aberdeen-managed DOM nodes and stops all active reactive scopes
 * (created by {@link mount}, {@link derive}, {@link A | A} with functions, etc.).
 *
 * This effectively cleans up the entire Aberdeen application state. Aside from in
 * automated tests, there should probably be little reason to call this function.
 */
export function unmountAll() {
	ROOT_SCOPE.remove();
	cssCount = 0;
}

/**
 * Executes a function or retrieves a value *without* creating subscriptions in the current reactive scope, and returns its result.
 *
 * This is useful when you need to access reactive data inside a reactive scope (like {@link A | A})
 * but do not want changes to that specific data to trigger a re-execute of the scope.
 * 
 * Note: You may also use {@link unproxy} to get to the raw underlying data structure, which can be used to similar effect.
 *
 * @param target - Either a function to execute, or an object (which may also be an Array or a Map) to index.
 * @param key - Optional key/index to use when `target` is an object.
 * @returns The result of the function call, or the value at `target[key]` when `target` is an object or `target.get(key)` when it's a Map.
 *
 * @example Peeking within observer
 * ```typescript
 * const $data = A.proxy({ a: 1, b: 2 });
 * A(() => {
 *   // re-executes only when $data.a changes, because $data.b is peeked.
 *   const b = A.peek(() => $data.b);
 *   console.log(`A is ${$data.a}, B was ${b} when A changed.`);
 * });
 * $data.b = 3; // Does not trigger console.log
 * $data.a = 2; // Triggers console.log (logs "A is 2, B was 3 when A changed.")
 * ```
 *
 */

export function peek<T extends object, K extends keyof T>(target: T, key: K): T[K];
export function peek<K,V>(target: Map<K,V>, key: K): V | undefined;
export function peek<T>(target: T[], key: number): T | undefined;
export function peek<T>(target: () => T): T;

export function peek(target: any, key?: any) {
	peeking++;
	try {
		if (arguments.length === 1) {
			return target();
		} else {
			return (target instanceof Map) ? target.get(key) : target[key];
		}
	} finally {
		peeking--;
	}
}

/** When using a Map as `source`. */
export function map<K, IN, OUT>(
	source: Map<K, IN>,
	func: (value: IN, key: K) => undefined | OUT,
): Map<K, OUT>;
/** When using an array as `source`. */
export function map<IN, OUT>(
	source: Array<IN>,
	func: (value: IN, index: number) => undefined | OUT,
): Array<OUT>;
/** When using an object as `source`. */
export function map<IN, const IN_KEY extends string | number | symbol, OUT>(
	source: Record<IN_KEY, IN>,
	func: (value: IN, index: KeyToString<IN_KEY>) => undefined | OUT,
): Record<string | symbol, OUT>;
/**
 * Reactively maps/filters items from a proxied source array or object to a new proxied array or object.
 *
 * It iterates over the `target` proxy. For each item, it calls `func`.
 * - If `func` returns a value, it's added to the result proxy under the same key/index.
 * - If `func` returns `undefined`, the item is skipped (filtered out).
 *
 * The returned proxy automatically updates when:
 * - Items are added/removed/updated in the `target` proxy.
 * - Any proxied data read *within* the `func` call changes (for a specific item).
 *
 * @param func - A function `(value, key) => mappedValue | undefined` that transforms each item.
 *   It receives the item's value and its key/index. Return `undefined` to filter the item out.
 * @returns A new proxied array or object containing the mapped values.
 * @template IN The type of items in the source proxy.
 * @template OUT The type of items in the resulting proxy.
 *
 * @example Map array values
 * ```typescript
 * const $numbers = A.proxy([1, 2, 3]);
 * const $doubled = A.map($numbers, (n) => n * 2);
 * // $doubled is proxy([2, 4, 6])
 *
 * A(() => console.log($doubled)); // Logs updates
 * $numbers.push(4); // $doubled becomes proxy([2, 4, 6, 8])
 * ```
 *
 * @example Filter and map object properties
 * ```typescript
 * const $users = A.proxy({
 *   'u1': { name: 'Alice', active: true },
 *   'u2': { name: 'Bob', active: false },
 *   'u3': { name: 'Charlie', active: true }
 * });
 *
 * const $activeUserNames = A.map($users, ($user) => $user.active ? $user.name : undefined);
 * // $activeUserNames is proxy({ u1: 'Alice', u3: 'Charlie' })
 * A(() => console.log(Object.values($activeUserNames)));
 *
 * $users.u2.active = true;
 * // $activeUserNames becomes proxy({ u1: 'Alice', u2: 'Bob', u3: 'Charlie' })
 * ```
 */
export function map(
	source: any,
	func: (value: any, key: any) => any,
): any {
	let out;
	if (source instanceof Array) {
		out = optProxy([]);
	} else if (source instanceof Map) {
		out = optProxy(new Map());
	} else {
		out = optProxy({});
	}

	onEach(source, (item: any, key: symbol | string | number) => {
		const value = func(item, key);
		if (value !== undefined) {
			if (out instanceof Map) {
				out.set(key, value);
				clean(() => {
					out.delete(key);
				});
			} else {
				out[key] = value;
				clean(() => {
					delete out[key];
				});
			}
		}
	});
	return out;
}

/** When using an array as `source`. */
export function multiMap<IN, OUT extends { [key: string | symbol]: any }>(
	source: Array<IN>,
	func: (value: IN, index: number) => OUT | undefined,
): OUT;
/** When using an object as `source`. */
export function multiMap<
	K extends string | number | symbol,
	IN,
	OUT extends { [key: string | symbol]: any },
>(source: Record<K, IN>, func: (value: IN, index: KeyToString<K>) => OUT | undefined): OUT;
/** When using a Map as `source`. */
export function multiMap<
	K,
	IN,
	OUT extends { [key: string | symbol]: any },
>(source: Map<K, IN>, func: (value: IN, key: K) => OUT | undefined): OUT;
/**
 * Reactively maps items from a source proxy (array or object) to a target proxied object,
 * where each source item can contribute multiple key-value pairs to the target.
 *
 * It iterates over the `target` proxy. For each item, it calls `func`.
 * - If `func` returns an object, all key-value pairs from that object are added to the result proxy.
 * - If `func` returns `undefined`, the item contributes nothing.
 *
 * The returned proxy automatically updates when:
 * - Items are added/removed/updated in the `target` proxy.
 * - Any proxied data read *within* the `func` call changes (for a specific item).
 * - If multiple input items produce the same output key, the last one processed usually "wins",
 *   but the exact behavior on collision depends on update timing.
 *
 * This is useful for "flattening" or "indexing" data, or converting an observable array to an observable object.
 *
 * @param source - The source proxied array or object.
 * @param func - A function `(value, key) => ({...pairs} | undefined)` that transforms an item
 *   into an object of key-value pairs to add, or `undefined` to add nothing.
 * @returns A new proxied object containing the aggregated key-value pairs.
 * @template IN The type of items in the source proxy.
 * @template OUT The type of the aggregated output object (should encompass all possible key-value pairs).
 *
 * @example Creating an index from an array
 * ```typescript
 * const $items = A.proxy([
 *   { id: 'a', value: 10 },
 *   { id: 'b', value: 20 },
 * ]);
 * const $itemsById = A.multiMap($items, ($item) => ({
 *   [$item.id]: $item.value,
 *   [$item.id+$item.id]: $item.value*10,
 * }));
 * // $itemsById is proxy({ a: 10, aa: 100, b: 20, bb: 200 })
 *
 * A(() => console.log($itemsById));
 *
 * $items.push({ id: 'c', value: 30 });
 * // $itemsById becomes proxy({ a: 10, aa: 100, b: 20, bb: 200, c: 30, cc: 300 })
 * ```
 */
export function multiMap(
	source: any,
	func: (value: any, key: any) => Record<string | symbol, any>,
): any {
	const out = optProxy({});
	onEach(source, (item: any, key: symbol | string | number) => {
		const pairs = func(item, key);
		if (pairs) {
			for (const key of Object.keys(pairs)) out[key] = pairs[key];
			clean(() => {
				for (const key of Object.keys(pairs)) delete out[key];
			});
		}
	});
	return out;
}

/** When using an object as `array`. */
export function partition<OUT_K extends string | number | symbol, IN_V>(
	source: IN_V[],
	func: (value: IN_V, key: number) => undefined | OUT_K | OUT_K[],
): Record<OUT_K, Record<number, IN_V>>;
/** When using an object as `source`. */
export function partition<
	IN_K extends string | number | symbol,
	OUT_K extends string | number | symbol,
	IN_V,
>(
	source: Record<IN_K, IN_V>,
	func: (value: IN_V, key: IN_K) => undefined | OUT_K | OUT_K[],
): Record<OUT_K, Record<IN_K, IN_V>>;
/** When using a Map as `source`. */
export function partition<
	IN_K extends string | number | symbol,
	OUT_K extends string | number | symbol,
	IN_V,
>(
	source: Map<IN_K, IN_V>,
	func: (value: IN_V, key: IN_K) => undefined | OUT_K | OUT_K[],
): Record<OUT_K, Record<IN_K, IN_V>>;

/**
 * @overload
 * Reactively partitions items from a source proxy (array or object) into multiple "bucket" proxies
 * based on keys determined by a classifier function.
 *
 * This function iterates through the `source` proxy using {@link onEach}. For each item,
 * it calls the classifier `func`, which should return:
 * - A single key (`OUT_K`): The item belongs to the bucket with this key.
 * - An array of keys (`OUT_K[]`): The item belongs to all buckets specified in the array.
 * - `undefined`: The item is not placed in any bucket.
 *
 * The function returns a main proxied object. The keys of this object are the bucket keys (`OUT_K`)
 * returned by `func`. Each value associated with a bucket key is another proxied object (the "bucket").
 * This inner bucket object maps the *original* keys/indices from the `source` to the items
 * themselves that were classified into that bucket.
 *
 * The entire structure is reactive. Changes in the `source` proxy (adding/removing/updating items)
 * or changes in dependencies read by the `func` will cause the output partitioning to update automatically.
 * Buckets are created dynamically as needed and removed when they become empty.
 *
 * @param source - The input proxied Array or Record (e.g., created by {@link proxy}) containing the items to partition.
 * @param func - A classifier function `(value: IN_V, key: IN_K | number) => undefined | OUT_K | OUT_K[]`.
 *   It receives the item's value and its original key/index from the `source`. It returns the bucket key(s)
 *   the item belongs to, or `undefined` to ignore the item.
 * @returns A proxied object where keys are the bucket identifiers (`OUT_K`) and values are proxied Records
 *   (`Record<IN_K | number, IN_V>`) representing the buckets. Each bucket maps original source keys/indices
 *   to the items belonging to that bucket.
 *
 * @template OUT_K - The type of the keys used for the output buckets (string, number, or symbol).
 * @template IN_V - The type of the values in the source proxy.
 * @template IN_K - The type of the keys in the source proxy (if it's a Record).
 *
 * @example Grouping items by a property
 * ```typescript
 * interface Product { id: string; category: string; name: string; }
 * const $products = A.proxy<Product[]>([
 *   { id: 'p1', category: 'Fruit', name: 'Apple' },
 *   { id: 'p2', category: 'Veg', name: 'Carrot' },
 *   { id: 'p3', category: 'Fruit', name: 'Banana' },
 * ]);
 *
 * // Partition products by category. Output keys are categories (string).
 * // Inner keys are original array indices (number).
 * const $productsByCategory = A.partition($products, ($product) => $product.category);
 *
 * // Reactively show the data structure
 * A.dump($productsByCategory);
 *
 * // Make random changes to the categories, to show reactiveness
 * setInterval(() => $products[0|(Math.random()*3)].category = ['Snack','Fruit','Veg'][0|(Math.random()*3)], 2000);
 * ```
 *
 * @example Item in multiple buckets
 * ```typescript
 * interface User { id: number; tags: string[]; name: string; }
 * const $users = A.proxy({
 *   'u1': { name: 'Alice', tags: ['active', 'new'] },
 *   'u2': { name: 'Bob', tags: ['active'] }
 * });
 *
 * // Partition users by tag. Output keys are tags (string).
 * // Inner keys are original object keys (string: 'u1', 'u2').
 * const $usersByTag = A.partition($users, ($user) => $user.tags);
 *
 * console.log($usersByTag);
 * ```
 */
export function partition<
	IN_K extends string | number | symbol,
	OUT_K extends string | number | symbol,
	IN_V,
>(
	source: Record<IN_K, IN_V>,
	func: (value: IN_V, key: KeyToString<IN_K>) => undefined | OUT_K | OUT_K[],
): Record<OUT_K, Record<KeyToString<IN_K>, IN_V>> {
	const unproxiedOut = {} as Record<OUT_K, Record<KeyToString<IN_K>, IN_V>>;
	const out = optProxy(unproxiedOut);
	onEach(source, (item: IN_V, key: KeyToString<IN_K>) => {
		const rsp = func(item, key);
		if (rsp != null) {
			const buckets = rsp instanceof Array ? rsp : [rsp];
			if (buckets.length) {
				for (const bucket of buckets) {
					if (unproxiedOut[bucket]) out[bucket][key] = item;
					else out[bucket] = { [key]: item } as Record<KeyToString<IN_K>, IN_V>;
				}
				clean(() => {
					for (const bucket of buckets) {
						delete out[bucket][key];
						if (isObjEmpty(unproxiedOut[bucket])) delete out[bucket];
					}
				});
			}
		}
	});
	return out;
}

/**
 * Renders a live, recursive dump of a proxied data structure (or any value)
 * into the DOM at the current {@link A | A} insertion point.
 *
 * Uses `<ul>` and `<li>` elements to display object properties and array items.
 * Updates reactively if the dumped data changes. Primarily intended for debugging purposes.
 *
 * @param data - The proxied data structure (or any value) to display.
 * @returns The original `data` argument, allowing for chaining.
 * @template T - The type of the data being dumped.
 *
 * @example Dumping reactive state
 * ```typescript
 * import A from 'aberdeen';
 *
 * const $state = A.proxy({
 *   user: { name: 'Frank', kids: 1 },
 *   items: ['a', 'b']
 * });
 *
 * A('h2#Live State Dump');
 * A.dump($state);
 *
 * // Change state later, the dump in the DOM will update
 * setTimeout(() => { $state.user.kids++; $state.items.push('c'); }, 2000);
 * ```
 */
export function dump<T>(data: T) {
	const org = dumpSeen;
	dumpSeen ||= new Set();
	try {
		rawDump(data, dumpSeen);
	} finally {
		dumpSeen = org;
	}
	return data;
}

let dumpSeen : undefined | Set<any>;

function rawDump<T>(data: T, seen: Set<any>) {
	if (data && typeof data === "object") {
		const name = data.constructor.name || "unknown object";
		if (seen.has(data)) {
			A(`#<${name}: circular reference>`);
			return;
		}
		seen.add(data);
		clean(() => seen.delete(data));

		const customDump = (data as any)[CUSTOM_DUMP];
		if (customDump !== undefined) {
			if (typeof customDump === 'function') customDump.call(data);
			else A(`#${customDump}`);
		} else {
			A(`#<${name}>`, "ul", () => {
				onEach(data as any, (value, key) => {
					A("li", () => {
						if (!(data instanceof Array)) A(`#${JSON.stringify(key)}: `);
						rawDump(value, seen);
					});
				});
			});
		}
	} else if (data === undefined) {
		A("#undefined");
	} else {
		A("#" + JSON.stringify(data));
	}
}

/**
 * When set on an object or its prototype chain, {@link dump} calls this as a render function
 * (with the object as `this`) instead of its default recursive rendering. If the value is not 
 * a function, it's treated as a string to display. 
 *
 * @example
 * ```typescript
 * class Color {
 *   constructor(public r: number, public g: number, public b: number) {}
 *   [CUSTOM_DUMP]() { A(`#rgb(${this.r}, ${this.g}, ${this.b})`); }
 * }
 * ```
 */
export const CUSTOM_DUMP = Symbol("CUSTOM_DUMP");

(Date.prototype as any)[CUSTOM_DUMP] = function(this: Date) {
	A("#<Date> " + this.toISOString());
};

		
/*
 * Helper functions
 */

/* c8 ignore start */
function internalError(code: number): never {
	throw new Error(`Aberdeen internal error ${code}`);
}
/* c8 ignore end */

function handleError(e: any, showMessage: boolean) {
	try {
		if (onError(e) === false) showMessage = false;
	} catch (e) {
		console.error(e);
	}
	try {
		if (showMessage) A("div.aberdeen-error#Error");
	} catch {
		// Error while adding the error marker to the DOM. Apparently, we're in
		// an awkward context. The error should already have been logged by
		// onError, so let's not confuse things by generating more errors.
	}
}

/** @internal */
export function withEmitHandler(
	handler: (
		target: TargetType,
		index: any,
		newData: any,
		oldData: any,
	) => void,
	func: () => void,
) {
	const oldEmitHandler = emit;
	emit = handler;
	try {
		func();
	} finally {
		emit = oldEmitHandler;
	}
}


// Automatically add cssVars and cssSnippets (from insertCss) into a <head> style tag
if (typeof document !== "undefined") {
	leakScope(() => {
		A(() => {
			if (isEmpty(cssSnippets) && isEmpty(cssVars)) return;
			mount(document.head, () => {
				A('style.abd', () => {
					onEach(cssSnippets, (value) => {
						A('#', value);
					});
					A(() => {
						if (isEmpty(cssVars)) return;
						let css = ":root{";
						for(const [key, value] of Object.entries(cssVars)) {
							const varName = DIGIT_FIRST.test(String(key)) ? `m${key}` : key;
							css += `--${varName}:${value};`;
						}
						css += "}\n";
						A('#', css);
					})
				});
			});
		});
	});
}

/**
 * The main Aberdeen API. `A` is itself a callable function for building reactive DOM trees
 * (creating elements, setting attributes, adding content). All other Aberdeen functions and
 * values are available as properties on `A`.
 *
 * @example Basic usage
 * ```typescript
 * import A from 'aberdeen';
 *
 * const $state = A.proxy({ count: 0 });
 * A('div', () => {
 *   A(`p#Count: ${$state.count}`);
 *   A('button text=+ click=', () => $state.count++);
 * });
 * ```
 */
export default Object.assign(A, {
	/** {@inheritDoc clean} */ clean,
	/** {@inheritDoc clone} */ clone,
	/** {@inheritDoc copy} */ copy,
	/** {@inheritDoc count} */ count,
	/** {@inheritDoc cssVars} */ cssVars,
	/** {@inheritDoc CUSTOM_DUMP} */ CUSTOM_DUMP,
	/** {@inheritDoc darkMode} */ darkMode,
	/** {@inheritDoc derive} */ derive,
	/** {@inheritDoc disableCreateDestroy} */ disableCreateDestroy,
	/** {@inheritDoc dump} */ dump,
	/** {@inheritDoc freeze} */ freeze,
	/** {@inheritDoc insertCss} */ insertCss,
	/** {@inheritDoc insertGlobalCss} */ insertGlobalCss,
	/** {@inheritDoc invertString} */ invertString,
	/** {@inheritDoc isEmpty} */ isEmpty,
	/** {@inheritDoc map} */ map,
	/** {@inheritDoc merge} */ merge,
	/** {@inheritDoc mount} */ mount,
	/** {@inheritDoc multiMap} */ multiMap,
	/** {@inheritDoc OPAQUE} */ OPAQUE,
	/** {@inheritDoc NO_COPY} */ NO_COPY,
	/** {@inheritDoc onEach} */ onEach,
	/** {@inheritDoc partition} */ partition,
	/** {@inheritDoc peek} */ peek,
	/** {@inheritDoc proxy} */ proxy,
	/** {@inheritDoc ref} */ ref,
	/** {@inheritDoc runQueue} */ runQueue,
	/** {@inheritDoc setErrorHandler} */ setErrorHandler,
	/** {@inheritDoc setSpacingCssVars} */ setSpacingCssVars,
	/** {@inheritDoc unmountAll} */ unmountAll,
	/** {@inheritDoc unproxy} */ unproxy,
});