aberdeen 0.4.0 → 1.0.0

package/dist/aberdeen.d.ts

@@ -1,599 +1,723 @@
 /**
- * Normally, changes to `Store`s are reacted to asynchronously, in an (optimized)
- * batch, after a timeout of 0s. Calling `runQueue()` will do so immediately
- * and synchronously. Doing so may be helpful in cases where you need some DOM
- * modification to be done synchronously.
+ * Forces the immediate and synchronous execution of all pending reactive updates.
  *
- * This function is re-entrant, meaning it is safe to call `runQueue` from a
- * function that is called due to another (automatic) invocation of `runQueue`.
+ * 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 = proxy("before");
+ *
+ * $({text: 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:
+ * runQueue();
+ *
+ * console.log(2, document.body.innerHTML); // after
+ * ```
  */
 export declare function runQueue(): void;
 /**
- * A promise-like object that you can `await`. It will resolve *after* the current batch
- * of DOM-write operations has completed. This is the best time to retrieve DOM properties
- * that dependent on a layout being completed, such as `offsetHeight`.
+ * 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.
+ * @private
+ */
+export type SortKeyType = number | string | Array<number | string> | undefined;
+/**
+ * Creates a new string that has the opposite sort order compared to the input string.
  *
- * By batching DOM reads separately from DOM writes, this prevents the browser from
- * interleaving layout reads and writes, which can force additional layout recalculations.
- * This helps reduce visual glitches and flashes by ensuring the browser doesn't render
- * intermediate DOM states during updates.
+ * 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.
  *
- * Unlike `setTimeout` or `requestAnimationFrame`, this mechanism ensures that DOM read
- * operations happen before any DOM writes in the same queue cycle, minimizing layout thrashing.
+ * **Warning:** The output string will likely contain non-printable characters or
+ * appear as gibberish and should not be displayed to the user.
  *
- * See `transitions.js` for some examples.
+ * @example
+ * ```typescript
+ * const users = proxy([
+ *     { id: 1, name: 'Charlie', score: 95 },
+ *     { id: 2, name: 'Alice', score: 100 },
+ *     { id: 3, name: 'Bob', score: 90 },
+ * ]);
+ *
+ * onEach(users, (user) => {
+ *     $(`p:${user.name}: ${user.score}`);
+ * }, (user) => 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 declare const DOM_READ_PHASE: {
-    then: (fulfilled: () => void) => any;
-};
+export declare function invertString(input: string): string;
+export declare function onEach<T>(target: Array<undefined | T>, render: (value: T, index: number) => void, makeKey?: (value: T, key: any) => SortKeyType): void;
+export declare function onEach<K extends string | number | symbol, T>(target: Record<K, undefined | T>, render: (value: T, index: K) => void, makeKey?: (value: T, key: K) => SortKeyType): void;
 /**
- * A promise-like object that you can `await`. It will resolve *after* the current
- * DOM_READ_PHASE has completed (if any) and after any DOM triggered by Aberdeen
- * have completed. This is a good time to do little manual DOM tweaks that depend
- * on a *read phase* first, like triggering transitions.
+ * Reactively checks if an observable array or object 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.
  *
- * By batching DOM writes separately from DOM reads, this prevents the browser from
- * interleaving layout reads and writes, which can force additional layout recalculations.
- * This helps reduce visual glitches and flashes by ensuring the browser doesn't render
- * intermediate DOM states during updates.
+ * @param proxied The observable array or object (obtained via `observe()`) to check.
+ * @returns `true` if the array has length 0 or the object has no own enumerable properties, `false` otherwise.
  *
- * Unlike `setTimeout` or `requestAnimationFrame`, this mechanism ensures that DOM write
- * operations happen after all DOM reads in the same queue cycle, minimizing layout thrashing.
+ * @example
+ * ```typescript
+ * const items = proxy([]);
  *
- * See `transitions.js` for some examples.
+ * // Reactively display a message if the items array is empty
+ * $('div', () => {
+ *     if (isEmpty(items)) {
+ *         $('p', 'i:No items yet!');
+ *     } else {
+ * 		   onEach(items, item=>$('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 declare const DOM_WRITE_PHASE: {
-    then: (fulfilled: () => void) => any;
-};
-export interface Store {
-    /**
-     * Return a `Store` deeper within the tree by resolving the given `path`,
-     * subscribing to every level.
-     * In case `undefined` is encountered while resolving the path, a newly
-     * created `Store` containing `undefined` is returned. In that case, the
-     * `Store`'s [[`isDetached`]] method will return `true`.
-     * In case something other than a collection is encountered, an error is thrown.
-     */
-    (...path: any[]): Store;
-}
-export declare class Store {
-    /**
-     * Create a new `Store` with `undefined` as its initial value.
-     */
-    constructor();
-    /**
-     * Create a new `Store`.
-     * @param value The initial value. Plain objects, arrays and `Map`s, are converted
-     * into a tree of nested `Store`s. When another `Store` is included somewhere in that
-     * input tree, a reference is made.
-     */
-    constructor(value: any);
-    /**
-     * @returns The index for this Store within its parent collection. This will be a `number`
-     * when the parent collection is an array, a `string` when it's an object, or any data type
-     * when it's a `Map`.
-     *
-     * @example
-     * ```
-     * let store = new Store({x: 123})
-     * let subStore = store.ref('x')
-     * subStore.get() // 123
-     * subStore.index() // 'x'
-     * ```
-     */
-    index(): any;
-    /**
-     * Retrieve the value for store, subscribing the observe scope to changes.
-     *
-     * @param depth Limit the depth of the retrieved data structure to this positive integer.
-     *    When `depth` is `1`, only a single level of the value at `path` is unpacked. This
-     *    makes no difference for primitive values (like strings), but for objects, maps and
-     *    arrays, it means that each *value* in the resulting data structure will be a
-     *    reference to the `Store` for that value.
-     *
-     * @returns The resulting value (or `undefined` if the `Store` does not exist).
-     */
-    get(depth?: number): any;
-    /**
-     * Exactly like {@link Store.get}, except that when executed from an observe scope,
-     * we will not subscribe to changes in the data retrieved data.
-     */
-    peek(depth?: number): any;
-    /**
-     * Like {@link Store.get}, but with return type checking.
-     *
-     * @param expectType A string specifying what type the.get is expected to return. Options are:
-     *    "undefined", "null", "boolean", "number", "string", "function", "array", "map"
-     *    and "object". If the store holds a different type of value, a `TypeError`
-     *    exception is thrown.
-     * @returns
-     */
-    getTyped(expectType: String, depth?: number): any;
-    /**
-     * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `number`.
-     * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
-     */
-    getNumber(): number;
-    /**
-     * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `string`.
-     * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
-     */
-    getString(): string;
-    /**
-     * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `boolean`.
-     * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
-     */
-    getBoolean(): boolean;
-    /**
-     * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `function`.
-     * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
-     */
-    getFunction(): (Function);
-    /**
-     * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `array`.
-     * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
-     */
-    getArray(depth?: number): any[];
-    /**
-     * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `object`.
-     * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
-     */
-    getObject(depth?: number): object;
-    /**
-     * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `map`.
-     * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
-     */
-    getMap(depth?: number): Map<any, any>;
-    /**
-     * Like {@link Store.get}, but with a default value (returned when the Store
-     * contains `undefined`). This default value is also used to determine the expected type,
-     * and to throw otherwise.
-     *
-     * @example
-     * ```
-     * let store = new Store({x: 42})
-     * store('x').getOr(99) // 42
-     * store('y').getOr(99) // 99
-     * store('x').getOr('hello') // throws TypeError (because 42 is not a string)
-     * ```
-     */
-    getOr<T>(defaultValue: T): T;
-    /**
-     * Checks if the collection held in `Store` is empty, and subscribes the current scope to changes of the emptiness of this collection.
-     *
-     * @returns When the collection is not empty `true` is returned. If it is empty or if the value is undefined, `false` is returned.
-     * @throws When the value is not a collection and not undefined, an Error will be thrown.
-     */
-    isEmpty(): boolean;
-    /**
-     * Returns the number of items in the collection held in Store, and subscribes the current scope to changes in this count.
-     *
-     * @returns The number of items contained in the collection, or 0 if the value is undefined.
-     * @throws When the value is not a collection and not undefined, an Error will be thrown.
-     */
-    count(): number;
-    /**
-     * Returns a strings describing the type of the `Store` value, subscribing to changes of this type.
-     * Note: this currently also subscribes to changes of primitive values, so changing a value from 3 to 4
-     * would cause the scope to be rerun. This is not great, and may change in the future. This caveat does
-     * not apply to changes made *inside* an object, `Array` or `Map`.
-     *
-     * @returns Possible options: "undefined", "null", "boolean", "number", "string", "function", "array", "map" or "object".
-     */
-    getType(): string;
-    /**
-     * Returns a new `Store` that will always hold either the value of `whenTrue` or the value
-     * of `whenFalse` depending on whether the original `Store` is truthy or not.
-     *
-     * @param whenTrue The value set to the return-`Store` while `this` is truthy. This can be
-     *     any type of value. If it's a `Store`, the return-`Store` will reference the same
-     *     data (so *no* deep copy will be made).
-     * @param whenFalse Like `whenTrue`, but for falsy values (false, undefined, null, 0, "").
-     * @returns A store holding the result value. The value will keep getting updated while
-     * the observe context from which `if()` was called remains active.
-     */
-    if(whenTrue: any[], whenFalse?: any[]): Store;
-    /**
-     * Sets the `Store` value to the given argument.
-     *
-     * When a `Store` is passed in as the value, its value will be copied (subscribing to changes). In
-     * case the value is an object, an `Array` or a `Map`, a *reference* to that data structure will
-     * be created, so that changes made through one `Store` will be reflected through the other. Be
-     * carefull not to create loops in your `Store` tree that way, as that would cause any future
-     * call to {@link Store.get} to throw a `RangeError` (Maximum call stack size exceeded.)
-     *
-     * If you intent to make a copy instead of a reference, call {@link Store.get} on the origin `Store`.
-     *
-     * @returns The `Store` itself, for chaining other methods.
-     *
-     * @example
-     * ```
-     * let store = new Store() // Value is `undefined`
-     *
-     * store.set(6)
-     * store.get() // 6
-     *
-     * store.set({}) // Change  value to an empty object
-     * store('a', 'b', 'c').set('d') // Create parent path as objects
-     * store.get() // {x: 6, a: {b: {c: 'd'}}}
-     *
-     * store.set(42) // Overwrites all of the above
-     * store.get() // 42
-     *
-     * store('x').set(6) // Throw Error (42 is not a collection)
-     * ```
-     */
-    set(newValue: any): Store;
-    /**
-     * Sets the `Store` to the given `mergeValue`, but without deleting any pre-existing
-     * items when a collection overwrites a similarly typed collection. This results in
-     * a deep merge.
-     *
-     * @returns The `Store` itself, for chaining other methods.
-     *
-     * @example
-     * ```
-     * let store = new Store({a: {x: 1}})
-     * store.merge({a: {y: 2}, b: 3})
-     * store.get() // {a: {x: 1, y: 2}, b: 3}
-     * ```
-     */
-    merge(mergeValue: any): Store;
-    /**
-     * Sets the value for the store to `undefined`, which causes it to be omitted from the map (or array, if it's at the end)
-     *
-     * @returns The `Store` itself, for chaining other methods.
-     *
-     * @example
-     * ```
-     * let store = new Store({a: 1, b: 2})
-     * store('a').delete()
-     * store.get() // {b: 2}
-     *
-     * store = new Store(['a','b','c'])
-     * store(1).delete()
-     * store.get() // ['a', undefined, 'c']
-     * store(2).delete()
-     * store.get() // ['a']
-     * store.delete()
-     * store.get() // undefined
-     * ```
-     */
-    delete(): Store;
-    /**
-     * Pushes a value to the end of the Array that is at the specified path in the store.
-     * If that store path is `undefined`, an Array is created first.
-     * The last argument is the value to be added, any earlier arguments indicate the path.
-     *
-     * @returns The index at which the item was appended.
-     * @throws TypeError when the store contains a primitive data type.
-     *
-     * @example
-     * ```
-     * let store = new Store()
-     * store.push(3) // Creates the array
-     * store.push(6)
-     * store.get() // [3,6]
-     *
-     * store = new Store({myArray: [1,2]})
-     * store('myArray').push(3)
-     * store.get() // {myArray: [1,2,3]}
-     * ```
-     */
-    push(newValue: any): number;
-    /**
-     * {@link Store.peek} the current value, pass it through `func`, and {@link Store.set} the resulting
-     * value.
-     * @param func The function transforming the value.
-     * @returns The `Store` itself, for chaining other methods.
-     */
-    modify(func: (value: any) => any): Store;
-    /**
-     * Iterate the specified collection (Array, Map or object), running the given code block for each item.
-     * When items are added to the collection at some later point, the code block will be ran for them as well.
-     * When an item is removed, the {@link Store.clean} handlers left by its code block are executed.
-     *
-     * @param renderer The function to be called for each item. It receives the item's `Store` object as its only argument.
-     * @param makeSortKey An optional function that, given an items `Store` object, returns a value to be sorted on.
-     *   This value can be a number, a string, or an array containing a combination of both. When undefined is returned,
-     *   the item is *not* rendered. If `makeSortKey` is not specified, the output will be sorted by `index()`.
-     */
-    onEach(renderer: (store: Store) => void, makeSortKey?: (store: Store) => any): void;
-    /**
-     * Derive a new `Store` from this `Store`, by reactively passing its value
-     * through the specified function.
-     * @param func Your function. It should accept a the input store's value, and return
-     *   a result to be reactively set to the output store.
-     * @returns The output `Store`.
-     * @example
-     * ```javascript
-     * const store = new Store(21)
-     * const double = store.derive(v => v*2)
-     * double.get() // 42
-     *
-     * store.set(100)
-     * runQueue() // Or after a setTimeout 0, due to batching
-     * double.get() // 200
-     * ```
-     */
-    derive(func: (value: any) => any): Store;
-    /**
-     * Applies a filter/map function on each item within the `Store`'s collection,
-     * and reactively manages the returned `Map` `Store` to hold any results.
-     *
-     * @param func - Function that transform the given store into an output value or
-     * `undefined` in case this value should be skipped:
-     *
-     * @returns - A array/map/object `Store` with the values returned by `func` and the
-     * corresponding keys from the original map, array or object `Store`.
-     *
-     * When items disappear from the `Store` or are changed in a way that `func` depends
-     * upon, the resulting items are removed from the output `Store` as well. When multiple
-     * input items produce the same output keys, this may lead to unexpected results.
-     */
-    map(func: (store: Store) => any): Store;
-    /**
-     * Applies a filter/map function on each item within the `Store`'s collection,
-     * each of which can deliver any number of key/value pairs, and reactively manages the
-     * returned map `Store` to hold any results.
-     *
-     * @param func - Function that transform the given store into output values
-     * that can take one of the following forms:
-     * - an `Object` or a `Map`: Each key/value pair will be added to the output `Store`.
-     * - anything else: No key/value pairs are added to the output `Store`.
-     *
-     * @returns - A map `Store` with the key/value pairs returned by all `func` invocations.
-     *
-     * When items disappear from the `Store` or are changed in a way that `func` depends
-     * upon, the resulting items are removed from the output `Store` as well. When multiple
-     * input items produce the same output keys, this may lead to unexpected results.
-     */
-    multiMap(func: (store: Store) => any): Store;
-    /**
-    * Dump a live view of the `Store` tree as HTML text, `ul` and `li` nodes at
-    * the current mount position. Meant for debugging purposes.
-    * @returns The `Store` itself, for chaining other methods.
-    */
-    dump(): Store;
+export declare function isEmpty(proxied: TargetType): boolean;
+/** @private */
+export interface ValueRef<T> {
+    value: T;
 }
 /**
- * Modifies the *parent* DOM element in the current reactive scope, or adds
- * new DOM elements to it.
- *
- * @param args - Arguments that define how to modify/create elements.
- *
- * ### String arguments
- * Create new elements with optional classes and text content:
- * ```js
- * $('div.myClass')              // <div class="myClass"></div>
- * $('span.c1.c2:Hello')         // <span class="c1 c2">Hello</span>
- * $('p:Some text')              // <p>Some text</p>
- * $('.my-thing')                // <div class="my-thing"></div>
- * $('div', 'span', 'p.cls')     // <div><span<p class="cls"></p></span></div>
- * $(':Just some text!')		 // Just some text! (No new element, just a text node)
+ * Reactively counts the number of properties in an objects.
+ *
+ * @param proxied The observable object to count. In case an `array` is passed in, a {@link ref} to its `.length` 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`.
+ *
+ * @example
+ * ```typescript
+ * const items = proxy({x: 3, y: 7} as any);
+ * const cnt = count(items);
+ *
+ * // Create a DOM text node for the count:
+ * $('div', {text: cnt});
+ * // <div>2</div>
+
+ * // Or we can use it in an {@link observe} function:
+ * observe(() => console.log("The count is now", cnt.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 declare function count(proxied: TargetType): ValueRef<number>;
+export declare function proxy<T extends DatumType>(target: Array<T>): Array<T extends number ? number : T extends string ? string : T extends boolean ? boolean : T>;
+export declare function proxy<T extends object>(target: T): T;
+export declare function proxy<T extends DatumType>(target: T): ValueRef<T extends number ? number : T extends string ? string : T extends boolean ? boolean : T>;
+/**
+ * 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.
  *
- * ### Object arguments
- * Set properties, attributes, events and special features:
- * ```js
- * // Classes (dot prefix)
- * $('div', {'.active': true})           // Add class
- * $('div', {'.hidden': false})          // Remove (or don't add) class
- * $('div', {'.selected': myStore})      // Reactively add/remove class
- *
- * // Styles (dollar prefixed and camel-cased CSS properties)
- * $('div', {$color: 'red'})             // style.color = 'red'
- * $('div', {$marginTop: '10px'})        // style.marginTop = '10px'
- * $('div', {$color: myColorStore})      // Reactively change color
- *
- * // Events (function values)
- * $('button', {click: () => alert()})   // Add click handler
- *
- * // Properties (boolean values, `selectedIndex`, `value`)
- * $('input', {disabled: true})          // el.disabled = true
- * $('input', {value: 'test'})           // el.value = 'test'
- * $('select', {selectedIndex: 2})       // el.selectedIndex = 2
- *
- * // Transitions
- * $('div', {create: 'fade-in'})         // Add class on create
- * $('div', {create: el => {...}})       // Run function on create
- * $('div', {destroy: 'fade-out'})       // Add class before remove
- * $('div', {destroy: el => {...}})      // Run function before remove
- *
- * // Content
- * $('div', {html: '<b>Bold</b>'})       // Set innerHTML
- * $('div', {text: 'Plain text'})        // Add text node
- * const myElement = document.createElement('video')
- * $('div', {element: myElement})        // Add existing DOM element
- *
- * // Regular attributes (everything else)
- * $('div', {title: 'Info'})             // el.setAttribute('title', 'info')
+ * @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 userProxy = proxy({ name: 'Frank' });
+ * const rawUser = unproxy(userProxy);
+ *
+ * // Log reactively
+ * $(() => console.log('proxied', userProxy.name));
+ * // The following will only ever log once, as we're not subscribing to any observable
+ * $(() => console.log('unproxied', rawUser.name));
+ *
+ * // This cause the first log to run again:
+ * setTimeout(() => userProxy.name += '!', 1000);
+ *
+ * // This doesn't cause any new logs:
+ * setTimeout(() => rawUser.name += '?', 2000);
+ *
+ * // Both userProxy and rawUser end up as `{name: 'Frank!?'}`
+ * setTimeout(() => {
+ *   console.log('final proxied', userProxy)
+ *   console.log('final unproxied', rawUser)
+ * }, 3000);
+ * ```
+ */
+export declare function unproxy<T>(target: T): T;
+/**
+ * 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 updates.
+ * - **Handles Proxies:** Can accept proxied or unproxied objects/arrays for both `dst` and `src`.
+ *
+ * @param dst - The destination object/array (proxied or unproxied).
+ * @param src - The source object/array (proxied or unproxied). It won't be modified.
+ * @param flags - Bitmask controlling copy behavior:
+ *   - {@link MERGE}: Performs a partial update. Properties in `dst` not present in `src` are kept.
+ *     `null`/`undefined` in `src` delete properties in `dst`. Handles partial array updates via object keys.
+ *   - {@link SHALLOW}: Performs a shallow copy; when an array/object of the right type doesn't exist in `dst` yet, a reference to the array/object in `src` will be made, instead of creating a copy. If the array/object already exists, it won't be replaced (by a reference), but all items will be individually checked and copied like normal, keeping changes (and therefore UI updates) to a minimum.
+ * @template T - The type of the objects being copied.
+ * @throws Error if attempting to copy an array into a non-array or vice versa (unless {@link MERGE} is set, allowing for sparse array updates).
+ *
+ * @example Basic Copy
+ * ```typescript
+ * const source = proxy({ a: 1, b: { c: 2 } });
+ * const dest = proxy({ b: { d: 3 } });
+ * copy(dest, source);
+ * console.log(dest); // proxy({ a: 1, b: { c: 2 } })
  * ```
  *
- * When a `Store` is passed as a value, a seperate observe-scope will
- * be created for it, such that when the `Store` changes, only *that*
- * UI property will need to be updated.
- * So in the following example, when `colorStore` changes, only the
- * `color` CSS property will be updated.
- * ```js
- * $('div', {
- *   '.active': activeStore,             // Reactive class
- *   $color: colorStore,                 // Reactive style
- *   text: textStore                     // Reactive text
- * })
+ * @example MERGE
+ * ```typescript
+ * const source = { b: { c: 99 }, d: undefined }; // d: undefined will delete
+ * const dest = proxy({ a: 1, b: { x: 5 }, d: 4 });
+ * copy(dest, source, MERGE);
+ * console.log(dest); // proxy({ a: 1, b: { c: 99, x: 5 } })
  * ```
  *
- * ### Two-way input binding
- * Set the initial value of an <input> <textarea> or <select> to that
- * of a `Store`, and then start reflecting user changes to the former
- * in the latter.
- * ```js
- * $('input', {bind: myStore})           // Binds input.value
+ * @example Partial Array Update with MERGE
+ * ```typescript
+ * const messages = proxy(['msg1', 'msg2', 'msg3']);
+ * const update = { 1: 'updated msg2' }; // Update using object key as index
+ * copy(messages, update, MERGE);
+ * console.log(messages); // proxy(['msg1', 'updated msg2', 'msg3'])
  * ```
- * This is a special case, as changes to the `Store` will *not* be
- * reflected in the UI.
  *
- * ### Function arguments
- * Create child scopes that re-run on observed `Store` changes:
- * ```js
- * $('div', () => {
- *   $(myStore.get() ? 'span' : 'p')     // Reactive element type
- * })
+ * @example SHALLOW
+ * ```typescript
+ * const source = { nested: [1, 2] };
+ * const dest = {};
+ * copy(dest, source, SHALLOW);
+ * dest.nested.push(3);
+ * console.log(source.nested); // [1, 2, 3] (source was modified)
  * ```
- * When *only* a function is given, `$` behaves exactly like {@link Store.observe},
- * except that it will only work when we're inside a `mount`.
+ */
+export declare function copy<T extends object>(dst: T, src: T, flags?: number): void;
+/** Flag to {@link copy} causing it to use merge semantics. See {@link copy} for details. */
+export declare const MERGE = 1;
+/** Flag to {@link copy} and {@link clone} causing them to create a shallow copy (instead of the deep copy done by default).*/
+export declare const SHALLOW = 2;
+/**
+ * Clone an (optionally proxied) object or array.
  *
- * @throws {ScopeError} If called outside an observable scope.
- * @throws {Error} If invalid arguments are provided.
+ * @param src The object or array to clone. If it is proxied, `clone` will subscribe to any changes to the (nested) data structure.
+ * @param flags
+ *   - {@link SHALLOW}: Performs a shallow clone, meaning that only the top-level array or object will be copied, while object/array values will just be references to the original data in `src`.
+ * @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 (by default) copy of `src`.
  */
-export declare function $(...args: (string | (() => void) | false | null | undefined | {
-    [key: string]: any;
-})[]): void;
+export declare function clone<T extends object>(src: T, flags?: number): T;
 /**
- * Set a custome error handling function, thast is called when an error occurs during rendering
- * while in a reactive scope. The default implementation logs the error to the console, and then
- * just returns `true`, which causes an 'Error' message to be displayed in the UI. When this function
- * returns `false`, the error is suppressed. This mechanism exists because rendering errors can occur
- * at any time, not just synchronous when making a call to Aberdeen, thus normal exception handling
- * is not always possible.
+ * 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 $} to create two-way data bindings
+ * with form elements, and for passing a reactive property to any of the {@link $} key-value pairs.
  *
- * @param handler The handler function, getting an `Error` as its argument, and returning `false`
- *    if it does *not* want an error message to be added to the DOM.
- *    When `handler is `undefined`, the default error handling will be reinstated.
+ * 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 = proxy({ color: 'orange', velocity: 42 });
+ *
+ * // Usage with `bind`
+ * $('input', {
+ *   type: 'text',
+ *   // Creates a two-way binding between the input's value and formData.username
+ *   bind: ref(formData, 'color')
+ * });
+ *
+ * // Usage as a dynamic property, causes a TextNode with just the name to be created and live-updated
+ * $('p:Selected color: ', {
+ *   text: ref(formData, 'color'),
+ *   $color: ref(formData, 'color')
+ * });
+ *
+ * // Changes are actually stored in formData - this causes logs like `{color: "Blue", velocity 42}`
+ * $(() => console.log(formData))
+ * ```
+ */
+export declare function ref<T extends TargetType, K extends keyof T>(target: T, index: K): ValueRef<T[K]>;
+/**
+ * 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`: 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**)* (':' **text**)?
+ *   meaning it consists of...
+ *   - An optional HTML **tag**, something like `h1`. If present, a DOM element of that tag is created, and that element will be the *current* element for the rest of this `$` function execution.
+ *   - Any number of CSS classes prefixed by `.` characters. These classes will be added to the *current* element.
+ *   - Optional content **text** prefixed by a `:` character, ranging til the end of the string. This will be added as a TextNode to the *current* element.
+ * - `function`: When a function (without argument nor a return value) is passed in, it will be reactively executed in its own observe scope, preserving the *current element*. So any `$()` invocations within this function will create DOM elements with our *current* element as parent. 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 `$`, have been cleaned - see also {@link clean}).
+ * - `object`: When an object is passed in, its key-value pairs are used to modify the *current* element in the following ways...
+ *   - `{<attrName>: any}`: The common case is setting the value as an HTML attribute named key. So `{placeholder: "Your name"}` would add `placeholder="Your name"` to the current HTML element.
+ *   - `{<propName>: boolean}` or `{value: any}` or `{selectedIndex: number}`: If the value is a boolean, or if the key is `value` or `selectedIndex`, it is set on the `current` element as a DOM property instead of an HTML attribute. For example `{checked: true}` would do `el.checked = true` for the *current* element.
+ *   - `{".class": boolean}`: 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 `{".hidden": hide}` would toggle the `hidden` CSS class.
+ *   - `{<eventName>: function}`: 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: `{click: myClickHandler}`.
+ *   - `{$<styleProp>: value}`: If the key starts with a `$` character, set a CSS style property with the name of the rest of the key to the given value. Example: `{$backgroundColor: 'red'}`.
+ *   - `{create: string}`: Add the value string as a CSS class to the *current* element, *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`.
+ *   - `{destroy: string}`: When the *current* element is a top-level element to be removed (due to reactivity cleanup), actual removal from the DOM is delayed by 2 seconds, and in the mean time the value string is added as a CSS class to the element, allowing for a deletion transition. The string may also contain multiple dot-separated CSS classes, such as `.fade.shrink`.
+ *   - `{create: function}` and `{destroy: function}`: The function is invoked when the *current* element is the top-level element being created/destroyed. It can be used for more involved creation/deletion animations. In case of `destroy`, the function is responsible for actually removing the element from the DOM (eventually). See `transitions.ts` in the Aberdeen source code for some examples.
+ *   - `{bind: <obsValue>}`: Create a two-way binding element between the `value` property of the given observable (proxy) variable, and the *current* input element (`<input>`, `<select>` or `<textarea>`). This is often used together with {@link ref}, in order to use properties other than `.value`.
+ *   - `{<any>: <obsvalue>}`: Create a new observe scope and read the `value` property of the given observable (proxy) variable from within it, and apply the contained value using any of the other rules in this list. Example:
+ *      ```typescript
+ *      const myColor = proxy('red');
+ *      $('p:Test', {$color: 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`.
+ *   - `{text: string|number}`: Add the value as a `TextNode` to the *current* element.
+ *   - `{html: string}`: Add the value as HTML to the *current* element. This should only be used in exceptional situations. And of course, beware of XSS.
+ *   - `{element: Node}`: Add a pre-existing HTML `Node` to the *current* element.
+ *
+ *
+ * @example Create Element
+ * ```typescript
+ * $('button.secondary.outline:Submit', {
+ *   disabled: true,
+ *   click: () => console.log('Clicked!'),
+ *   $color: 'red'
+ * });
+ * ```
+ *
+ * @example Nested Elements & Reactive Scope
+ * ```typescript
+ * const state = proxy({ count: 0 });
+ * $('div', () => { // Outer element
+ *   // This scope re-renders when state.count changes
+ *   $('p:Count is ${state.count}`);
+ *   $('button:Increment', { click: () => state.count++ });
+ * });
+ * ```
+ *
+ * @example Two-way Binding
+ * ```typescript
+ * const user = proxy({ name: '' });
+ * $('input', { placeholder: 'Name', bind: ref(user, 'name') });
+ * $('h3', () => { // Reactive scope
+ *   $(`:Hello ${user.name || 'stranger'}`);
+ * });
+ * ```
+ *
+ * @example Conditional Rendering
+ * ```typescript
+ * const show = proxy(false);
+ * $('button', { click: () => show.value = !show.value }, () => $(show.value ? ':Hide' : ':Show'));
+ * $(() => { // Reactive scope
+ *   if (show.value) {
+ *     $('p:Details are visible!');
+ *   }
+ * });
+ * ```
+ */
+export declare function $(...args: (string | null | undefined | false | (() => void) | Record<string, any>)[]): void;
+/**
+ * Inserts CSS rules into the document, optionally scoping them with a unique class name.
+ *
+ * Takes a JavaScript object representation of CSS rules. camelCased property keys are
+ * converted to kebab-case (e.g., `fontSize` becomes `font-size`).
+ *
+ * @param style - An object where keys are CSS selectors (or camelCased properties) and values are
+ *   CSS properties or nested rule objects.
+ *   - Selectors are usually combined as a descendant-relationship (meaning just a space character) with their parent selector.
+ *   - In case a selector contains a `&`, that character will be replaced by the parent selector.
+ *   - Selectors will be split on `,` characters, each combining with the parent selector with *or* semantics.
+ *   - Selector starting with `'@'` define at-rules like media queries. They may be nested within regular selectors.
+ * @param global - If `true`, styles are inserted globally without prefixing.
+ *                 If `false` (default), all selectors are prefixed with a unique generated
+ *                 class name (e.g., `.AbdStl1`) to scope the styles.
+ * @returns The unique class name prefix used for scoping (e.g., `.AbdStl1`), or an empty string
+ *          if `global` was `true`. Use this prefix with {@link $} to apply the styles.
+ *
+ * @example Scoped Styles
+ * ```typescript
+ * const scopeClass = insertCss({
+ *   color: 'red',
+ *   padding: '10px',
+ *   '&:hover': { // Use '&' for the root scoped selector
+ *     backgroundColor: '#535'
+ *   },
+ *   '.child-element': { // Nested selector
+ *     fontWeight: 'bold'
+ *   },
+ *   '@media (max-width: 600px)': {
+ *     padding: '5px'
+ *   }
+ * });
+ * // scopeClass might be ".AbdStl1"
+ *
+ * // Apply the styles
+ * $(scopeClass, () => { // Add class to the div
+ *   $(`:Scoped content`);
+ *   $('div.child-element:Child'); // .AbdStl1 .child-element rule applies
+ * });
+ * ```
+ *
+ * @example Global Styles
+ * ```typescript
+ * insertCss({
+ *   '*': {
+ *     fontFamily: 'monospace',
+ *   },
+ *   'a': {
+ *     textDecoration: 'none',
+ *     color: "#107ab0",
+ *   }
+ * }, true); // Pass true for global
+ *
+ * $('a:Styled link');
+ * ```
+ */
+export declare function insertCss(style: object, global?: boolean): string;
+/**
+ * Sets a custom error handler function for errors that occur asynchronously
+ * within reactive scopes (e.g., during updates triggered by proxy changes in
+ * {@link observe} or {@link $} 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
  * setErrorHandler(error => {
- *    // Tell our developers about the problem.
- * 	  fancyErrorLogger(error)
- *    // Add custom error message to the DOM.
- *    try {
- *        $('.error:Sorry, something went wrong!')
- *    } catch() {} // In case there is no parent element.
- *    // Don't add default error message to the DOM.
- * 	  return false
+ *   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
+ *     $('div.error-message:Oops, something went wrong!');
+ *   } catch (e) {
+ *     // Ignore errors during error handling itself
+ *   }
+ *
+ *   return false; // Suppress default console log and DOM error message
+ * });
+ *
+ * // Styling for our custom error message
+ * insertCss({
+ *   '.error-message': {
+ *     backgroundColor: '#e31f00',
+ *     display: 'inline-block',
+ *     color: 'white',
+ *     borderRadius: '3px',
+ *     padding: '2px 4px',
+ *   }
+ * }, true); // global style
+ *
+ * // Cause an error within a render scope.
+ * $('div.box', () => {
+ *   // Will cause our error handler to insert an error message within the box
+ *   noSuchFunction();
  * })
  * ```
  */
 export declare function setErrorHandler(handler?: (error: Error) => boolean | undefined): void;
 /**
- * Return the browser Element that nodes would be rendered to at this point.
- * NOTE: Manually changing the DOM is not recommended in most cases. There is
- * usually a better, declarative way. Although there are no hard guarantees on
- * how your changes interact with Aberdeen, in most cases results will not be
- * terribly surprising. Be careful within the parent element of onEach() though.
+ * Gets the parent DOM `Element` where nodes created by {@link $} would currently be inserted.
+ *
+ * This is context-dependent based on the current reactive scope (e.g., inside a {@link mount}
+ * call or a {@link $} element's render function).
+ *
+ * **Note:** While this provides access to the DOM element, directly manipulating it outside
+ * of Aberdeen's control is generally discouraged. Prefer declarative updates using {@link $}.
+ *
+ * @returns The current parent `Element` for DOM insertion.
+ *
+ * @example Get parent for attaching a third-party library
+ * ```typescript
+ * function thirdPartyLibInit(parentElement) {
+ *   parentElement.innerHTML = "This element is managed by a <em>third party</em> lib."
+ * }
+ *
+ * $('div.box', () => {
+ *   // Get the div.box element just created
+ *   const containerElement = getParentElement();
+ *   thirdPartyLibInit(containerElement);
+ * });
+ * ```
  */
 export declare function getParentElement(): Element;
 /**
- * Register a function that is to be executed right before the current reactive scope
- * disappears or redraws.
- * @param clean - The function to be executed.
+ * 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 observe}, {@link mount}, {@link $} (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 myArray = proxy([3, 5, 10]);
+ * let sum = proxy(0);
+ *
+ * // Show the array items and maintain the sum
+ * onEach(myArray, (item, index) => {
+ *     $(`code:${index}→${item}`);
+ *     // We'll update sum.value using peek, as += first does a read, but
+ *     // we don't want to subscribe.
+ *     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
+ *     // observe scope.
+ *     clean(() => sum.value -= item);
+ * })
+ *
+ * // Show the sum
+ * $('h1', {text: sum});
+ *
+ * // Make random changes to the array
+ * const rnd = () => 0|(Math.random()*20);
+ * setInterval(() => myArray[rnd()] = rnd(), 1000);
+ * ```
  */
-export declare function clean(clean: () => void): void;
+export declare function clean(cleaner: () => void): void;
 /**
- * Reactively run a function, meaning the function will rerun when any `Store` that was read
- * during its execution is updated.
- * Calls to `observe` can be nested, such that changes to `Store`s read by the inner function do
- * no cause the outer function to rerun.
+ * 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.
  *
- * @param func - The function to be (repeatedly) executed.
- * @returns The mount id (usable for `unmount`) if this is a top-level observe.
- * @example
+ * 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 $} within this function. Its return value will be made available as an
+ *   observable returned by the `observe()` function.
+ * @returns An observable object, with its `value` property containing whatever the last run of `func` returned.
+ *
+ * @example Observation creating a UI components
+ * ```typescript
+ * const data = proxy({ user: 'Frank', notifications: 42 });
+ *
+ * $('main', () => {
+ *   console.log('Welcome');
+ *   $('h3:Welcome, ' + data.user); // Reactive text
+ *
+ *   observe(() => {
+ *     // When data.notifications changes, only this inner scope reruns,
+ *     // leaving the `<p>Welcome, ..</p>` untouched.
+ *     console.log('Notifications');
+ *     $('code.notification-badge:' + data.notifications);
+ *     $('a:Notify!', {click: () => data.notifications++});
+ *   });
+ * });
  * ```
- * let number = new Store(0)
- * let doubled = new Store()
- * setInterval(() => number.set(0|Math.random()*100)), 1000)
  *
- * observe(() => {
- *   doubled.set(number.get() * 2)
- * })
+ * ***Note*** that the above could just as easily be done using `$(func)` instead of `observe(func)`.
  *
- * observe(() => {
- *   console.log(doubled.get())
+ * @example Observation with return value
+ * ```typescript
+ * const counter = proxy(0);
+ * setInterval(() => counter.value++, 1000);
+ * const double = observe(() => counter.value * 2);
+ *
+ * $('h3', () => {
+ *     $(`:counter=${counter.value} double=${double.value}`);
  * })
+ * ```
+ *
+ * @overload
+ * @param func Func without a return value.
  */
-export declare function observe(func: () => void): number | undefined;
-/**
- * Like `observe`, but instead of deferring running the observer function until
- * a setTimeout 0, run it immediately and synchronously when a change to one of
- * the observed  `Store`s is made. Use this sparingly, as this prevents Aberdeen
- * from doing the usual batching and smart ordering of observers, leading to
- * performance problems and observing of 'weird' partial states.
- * @param func The function to be (repeatedly) executed.
- * @returns The mount id (usable for `unmount`) if this is a top-level observe.
- */
-export declare function immediateObserve(func: () => void): number | undefined;
+export declare function observe<T extends (DatumType | void)>(func: () => T): ValueRef<T>;
 /**
- * Reactively run the function, adding any DOM-elements created using {@link $} to the given parent element.
-
- * @param func - The function to be (repeatedly) executed, possibly adding DOM elements to `parentElement`.
- * @param parentElement - A DOM element that will be used as the parent element for calls to `$`.
- * @returns The mount id (usable for `unmount`) if this is a top-level mount.
+ * Similar to {@link observe}, creates a reactive scope that re-executes the function
+ * when its proxied dependencies change.
+ *
+ * **Difference:** Updates run **synchronously and immediately** after the proxy modification
+ * that triggered the update occurs.
+ *
+ * **Caution:** Use sparingly. Immediate execution bypasses Aberdeen's usual batching and
+ * ordering optimizations, which can lead to performance issues or observing inconsistent
+ * intermediate states if multiple related updates are applied sequentially.
+ * Prefer {@link observe} or {@link $} for most use cases.
+ *
+ * @param func - The function to execute reactively and synchronously.
  *
  * @example
- * ```
- * let store = new Store(0)
- * setInterval(() => store.modify(v => v+1), 1000)
+ * ```javascript
+ * const state = proxy({ single: 'A' });
  *
- * mount(document.body, () => {
- * 	   $(`h2:${store.get()} seconds have passed`)
- * })
- * ```
+ * immediateObserve(() => {
+ *   state.double = state.single + state.single
+ * });
+ * console.log(state.double); // 'AA'
  *
- * An example nesting {@link Store.observe} within `mount`:
+ * state.single = 'B';
+ * // Synchronously:
+ * console.log(state.double); // 'BB'
  * ```
- * let selected = new Store(0)
- * let colors = new Store(new Map())
+ */
+export declare function immediateObserve(func: () => void): void;
+/**
+ * Attaches a reactive Aberdeen UI fragment to an existing DOM element. Without the use of
+ * this function, {@link $} will assume `document.body` as its root.
  *
- * mount(document.body, () => {
- *   // This function will never rerun (as it does not read any `Store`s)
- *   $('button:<<', {click: () => selected.modify(n => n-1)})
- *   $('button:>>', {click: () => selected.modify(n => n+1)})
+ * 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.
  *
- *   observe(() => {
- *     // This will rerun whenever `selected` changes, recreating the <h2> and <input>.
- *     $('h2', {text: '#' + selected.get()})
- *     $('input', {type: 'color', value: '#ffffff' bind: colors(selected.get())})
- *   })
+ * Calls to {@link $} inside `func` will append nodes to `parentElement`.
+ * You can nest {@link observe} or other {@link $} scopes within `func`.
+ * Use {@link unmountAll} to clean up all mounted scopes and their DOM nodes.
  *
- *   observe(() => {
- *     // This function will rerun when `selected` or the selected color changes.
- *     // It will change the <body> background-color.
- *     $({$backgroundColor: colors.get(selected.get()) || 'white'})
- *   })
- * })
+ * Mounting scopes happens reactively, meaning that if this function is called from within another
+ * ({@link observe} or {@link $} 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 $}.
+ *
+ * @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 { mount, $, proxy } from 'aberdeen';
+ *
+ * const runTime = proxy(0);
+ * setInterval(() => runTime.value++, 1000);
+ *
+ * mount(document.getElementById('app-root'), () => {
+ *   $('h4:Aberdeen App');
+ *   $(`p:Run time: ${runTime.value}s`);
+ *   // Conditionally render some content somewhere else in the static page
+ *   if (runTime.value&1) {
+ *     mount(document.getElementById('title-extra'), () =>
+ *       $(`i:(${runTime.value}s)`)
+ *     );
+ *   }
+ * });
  * ```
-*/
-export declare function mount(parentElement: Element, func: () => void): number | undefined;
+ *
+ * Note how the inner mount behaves reactively as well, automatically unmounting when it's parent observer scope re-runs.
+ */
+export declare function mount(parentElement: Element, func: () => void): void;
 /**
- * Unmount one specific or all top-level mounts or observes, meaning those that were created outside of the scope
- * of any other mount or observe.
- * @param id Optional mount number (as returned by `mount`, `observe` or `immediateObserve`). If `undefined`, unmount all.
+ * Removes all Aberdeen-managed DOM nodes and stops all active reactive scopes
+ * (created by {@link mount}, {@link observe}, {@link $} with functions, etc.).
+ *
+ * This effectively cleans up the entire Aberdeen application state.
  */
-export declare function unmount(id?: number): void;
-/** Runs the given function, while not subscribing the current scope when reading {@link Store.Store} values.
+export declare function unmountAll(): void;
+/**
+ * Executes a function *without* creating subscriptions in the current reactive scope, and returns its result.
  *
- * @param func Function to be executed immediately.
- * @returns Whatever `func()` returns.
- * @example
- * ```
- * import {Store, peek, text} from aberdeen
+ * This is useful when you need to access reactive data inside a reactive scope (like {@link observe})
+ * but do not want changes to that specific data to trigger a re-execute of the scope.
  *
- * let store = new Store(['a', 'b', 'c'])
+ * @template T The type of the return value of your function.
  *
- * mount(document.body, () => {
- *     // Prevent rerender when store changes
- *     let msg = peek(() => `Store has ${store.count()} elements, and the first is ${store.get(0)}`))
- *     text(msg)
- * })
+ * @param func - The function to execute without creating subscriptions.
+ * @returns Whatever `func` returns.
+ *
+ * @example Peeking within observe
+ * ```typescript
+ * const data = proxy({ a: 1, b: 2 });
+ * observe(() => {
+ *   // re-executes only when data.a changes, because data.b is peeked.
+ *   const b = 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.")
  * ```
  *
- * In the above example `store.get(0)` could be replaced with `store.peek(0)` to achieve the
- * same result without `peek()` wrapping everything. There is no non-subscribing equivalent
- * for `count()` however.
  */
 export declare function peek<T>(func: () => T): T;
+/** When using an object as `source`. */
+export declare function map<IN, OUT>(source: Record<string | symbol, IN>, func: (value: IN, index: string | symbol) => undefined | OUT): Record<string | symbol, OUT>;
+/** When using an array as `source`. */
+export declare function map<IN, OUT>(source: Array<IN>, func: (value: IN, index: number) => undefined | OUT): Array<OUT>;
+/** When using an array as `source`. */
+export declare function multiMap<IN, OUT extends {
+    [key: string | symbol]: DatumType;
+}>(source: Array<IN>, func: (value: IN, index: number) => OUT | undefined): OUT;
+/** When using an object as `source`. */
+export declare function multiMap<K extends string | number | symbol, IN, OUT extends {
+    [key: string | symbol]: DatumType;
+}>(source: Record<K, IN>, func: (value: IN, index: K) => OUT | undefined): OUT;
+/** When using an object as `array`. */
+export declare 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 declare 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>>;
+/**
+ * Renders a live, recursive dump of a proxied data structure (or any value)
+ * into the DOM at the current {@link $} 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 { $, proxy, dump } from 'aberdeen';
+ *
+ * const state = proxy({
+ *   user: { name: 'Frank', kids: 1 },
+ *   items: ['a', 'b']
+ * });
+ *
+ * $('h2:Live State Dump');
+ * dump(state);
+ *
+ * // Change state later, the dump in the DOM will update
+ * setTimeout(() => { state.user.kids++; state.items.push('c'); }, 2000);
+ * ```
+ */
+export declare function dump<T>(data: T): T;
 declare global {
     interface String {
         replaceAll(from: string, to: string): string;