@lexriver/dome 2.0.0 → 2.0.2

package/README.md

@@ -1350,7 +1350,7 @@ DomeManipulator.scrollToY({
 Use DomeRouter for navigation in single page app.
 
 ```typescript
-DomeRouter.onRoute('/about', true, async (params, url) => {
+DomeRouter.onRoute('/about', true, async (params, url, scrollTo, query) => {
     const { PageAbout } = await import('./pages/PageAbout') // dynamic import component
     DomeManipulator.replaceAllChildrenAsync(divContainer, <PageAbout />, animationHide, animationShow) // replace current page with new page
 })
@@ -1507,12 +1507,18 @@ Parameters:
 Where `RouteAction` type is:
 ```typescript
 export type RouteAction = (
-    params:{[key:string]:string}, // parameters from url
-    url:string, 
-    scrollToPreviousPositionAsync:()=>Promise<void> // this function can be called to scroll to previous page position
+    params:{[key:string]:string|number}, // parameters from url path
+    url:string, // url path without query string
+    scrollToPreviousPositionAsync:()=>Promise<void>, // this function can be called to scroll to previous page position
+    query:{[key:string]:string} // query parameters from window.location.search
     ) => void|Promise<void>
 ```
 
+For example, for URL `/search?category=books&sort=price`, the `query` parameter will be:
+```typescript
+{category: 'books', sort: 'price'}
+```
+
 example:
 ```typescript
 DomeRouter.onRoute('/login', true, (params, url) => changePage(<PageLogin />))

package/out/src/DomeComponent.d.mts

@@ -8,13 +8,16 @@ export declare abstract class DomeComponent<Attrs> {
     attrs: Attrs & InternalAttrs;
     children: any;
     rootElement: Element | HTMLElement;
+    private updateInProgress;
+    private updateRequested;
     constructor(attrs: Attrs & InternalAttrs, children: any);
     protected init(): void;
     protected abstract render(): HTMLElement;
     protected afterRender(): void;
     updateAsync(): Promise<void>;
+    private runScheduledUpdateAsync;
     scheduleUpdate: {
-        (this: unknown, ...args: [] & any[]): Promise<void>;
+        (this: unknown, ...args: [] & any[]): Promise<Promise<void>>;
         cancel: (reason?: any) => void;
     };
     protected afterUpdate(): void;

package/out/src/DomeComponent.mjs

@@ -4,6 +4,8 @@ export class DomeComponent {
     attrs;
     children;
     rootElement;
+    updateInProgress = false;
+    updateRequested = false;
     constructor(attrs, children) {
         //this.init()
         this.attrs = attrs;
@@ -35,9 +37,28 @@ export class DomeComponent {
         //console.timeEnd('browser')
         this.afterUpdate();
     }
-    scheduleUpdate = debounce(() => {
-        this.updateAsync();
-    }, 5);
+    async runScheduledUpdateAsync() {
+        if (this.updateInProgress) {
+            this.updateRequested = true;
+            return;
+        }
+        this.updateInProgress = true;
+        try {
+            do {
+                this.updateRequested = false;
+                try {
+                    await this.updateAsync();
+                }
+                catch (error) {
+                    console.error('DomeComponent: scheduled update failed', error);
+                }
+            } while (this.updateRequested);
+        }
+        finally {
+            this.updateInProgress = false;
+        }
+    }
+    scheduleUpdate = debounce(() => this.runScheduledUpdateAsync(), 5);
     afterUpdate() {
     }
 }

package/out/src/DomeManipulator.d.mts

@@ -16,6 +16,10 @@ export declare namespace DomeManipulator {
     function removeAllChildrenAsync(element: Element, animation?: Animation): Promise<void>;
     function appendChildAsync(containerElement: Element, child: Element, animation?: Animation): Promise<void>;
     function appendChildrenAsync(containerElement: Element, children: Element | Element[] | DocumentFragment | Text | string | null | undefined, animation?: Animation): Promise<void>;
+    /**
+     * Replacements for the same container run in call order. A rejected replacement does
+     * not block the queue, and replacements for different containers remain independent.
+     */
     function replaceAllChildrenAsync(containerElement: Element, childrenToInsert: Element | Element[] | DocumentFragment | Text | string | null | undefined, animationForHide?: Animation, animationForShow?: Animation): Promise<void>;
     function isInDom(el: Element | undefined): boolean;
     function isOnScreen(el: Element | undefined): boolean;

package/out/src/DomeManipulator.mjs

@@ -1,6 +1,7 @@
 import { Async } from "@lexriver/async";
 import { DataTypes } from "@lexriver/data-types";
 import { checkIfObservable } from "@lexriver/observable";
+const replacementPromiseByElement = new WeakMap();
 export var DomeManipulator;
 (function (DomeManipulator) {
     async function hideElementAsync(element, animation) {
@@ -121,8 +122,8 @@ export var DomeManipulator;
             forEachChildrenOf(element, (child) => child.nodeType == Node.ELEMENT_NODE && child.classList.add(animation.cssClassName));
             //console.log('##', 'wait ms', animation.timeMs)
             await Async.waitMsAsync(animation.timeMs);
-            //console.log('##', 'removing children', element.childNodes)
-            forEachChildrenOf(element, (child) => child.remove());
+            // Take a snapshot because childNodes is live and shrinks as nodes are removed.
+            Array.from(element.childNodes).forEach(child => child.remove());
             //console.log('##', 'done')
         }
         // if(element.children.length>0) {
@@ -152,19 +153,29 @@ export var DomeManipulator;
         }
     }
     DomeManipulator.appendChildrenAsync = appendChildrenAsync;
+    /**
+     * Replacements for the same container run in call order. A rejected replacement does
+     * not block the queue, and replacements for different containers remain independent.
+     */
     async function replaceAllChildrenAsync(containerElement, childrenToInsert, animationForHide, animationForShow) {
-        //await removeAllChildrenAsync(containerElement, animationForHide)
-        if (containerElement.childNodes.length > 0) {
-            await removeAllChildrenAsync(containerElement, animationForHide);
+        const previousReplacement = replacementPromiseByElement.get(containerElement);
+        const replacement = (previousReplacement ?? Promise.resolve())
+            .catch(() => undefined)
+            .then(async () => {
+            if (containerElement.childNodes.length > 0) {
+                await removeAllChildrenAsync(containerElement, animationForHide);
+            }
+            await appendChildrenAsync(containerElement, childrenToInsert, animationForShow);
+        });
+        replacementPromiseByElement.set(containerElement, replacement);
+        try {
+            await replacement;
+        }
+        finally {
+            if (replacementPromiseByElement.get(containerElement) === replacement) {
+                replacementPromiseByElement.delete(containerElement);
+            }
         }
-        // while(containerElement.childNodes.length>0){
-        //     await removeAllChildrenAsync(containerElement, animationForHide) // can be executed more than once! TODO: why?
-        // }
-        // if(containerElement.children.length>0) {
-        //     console.error('DomeManipulator: replaceAllChildenrAsync() failed:', 'containerElement.children.length=', containerElement.children.length, 'children=', containerElement.children, 'containerElement=', containerElement, 'animationForHide=', animationForHide)
-        //     throw new Error()
-        // }
-        await appendChildrenAsync(containerElement, childrenToInsert, animationForShow);
     }
     DomeManipulator.replaceAllChildrenAsync = replaceAllChildrenAsync;
     function isInDom(el) {

package/out/src/DomeRouter.d.mts

@@ -1,6 +1,8 @@
 export type RouteAction = (params: {
+    [key: string]: string | number;
+}, url: string, scrollToPreviousPositionAsync: () => Promise<void>, query: {
     [key: string]: string;
-}, url: string, scrollToPreviousPositionAsync: () => Promise<void>) => void | Promise<void>;
+}) => void | Promise<void>;
 export declare namespace DomeRouter {
     let maxHistoryUrlsCount: number;
     function navigate(url: string): void;

package/out/src/DomeRouter.mjs

@@ -182,7 +182,20 @@ export var DomeRouter;
             return [name.substring(1), value];
         }
     }
+    function parseQueryString(search) {
+        const query = {};
+        if (!search || search[0] !== '?')
+            return query;
+        const params = new URLSearchParams(search.substring(1));
+        for (const [key, value] of params.entries()) {
+            query[key] = value;
+        }
+        return query;
+    }
     async function executeAsync(url = window.location.pathname, scrollToPosition) {
+        const queryString = window.location.search;
+        const query = parseQueryString(queryString);
+        url = url.split('?')[0]; // Strip query params
         //const url = window.location.pathname
         const urlSlices = getRouteSlices(url);
         // urlSlices = show, category, 345
@@ -225,7 +238,7 @@ export var DomeRouter;
                     await DomeManipulator.scrollToAsync({
                         pxFromTop: scrollToPosition
                     });
-                });
+                }, query);
             }
         }
         if (countOfFoundRoutes == 0 && onNotFoundAction) {

package/out/src/concurrent-updates.test.d.mts

@@ -0,0 +1 @@
+export {};

package/out/src/concurrent-updates.test.mjs

@@ -0,0 +1,203 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { DomeComponent } from './DomeComponent.mjs';
+import { DomeManipulator } from './DomeManipulator.mjs';
+class FakeElement {
+    nodeType = 1;
+    childNodes = [];
+    classList = {
+        values: new Set(),
+        add: (name) => this.classList.values.add(name),
+        remove: (name) => this.classList.values.delete(name)
+    };
+    parentNode = null;
+    throwOnAppend = false;
+    get firstChild() {
+        return this.childNodes[0] ?? null;
+    }
+    appendChild(child) {
+        if (child.throwOnAppend) {
+            throw new Error('append failed');
+        }
+        child.parentNode = this;
+        this.childNodes.push(child);
+        return child;
+    }
+    remove() {
+        if (!this.parentNode)
+            return;
+        const index = this.parentNode.childNodes.indexOf(this);
+        if (index >= 0) {
+            this.parentNode.childNodes.splice(index, 1);
+        }
+        this.parentNode = null;
+    }
+}
+const asElement = (element) => element;
+const animation = (name) => ({ cssClassName: name, timeMs: 5 });
+const waitAsync = (timeMs) => new Promise(resolve => setTimeout(resolve, timeMs));
+async function waitForAsync(condition) {
+    const timeoutAt = Date.now() + 500;
+    while (!condition()) {
+        if (Date.now() >= timeoutAt) {
+            throw new Error('Timed out waiting for condition');
+        }
+        await waitAsync(1);
+    }
+}
+function deferred() {
+    let resolve;
+    const promise = new Promise(resolvePromise => {
+        resolve = resolvePromise;
+    });
+    return { promise, resolve };
+}
+const originalNode = Object.getOwnPropertyDescriptor(globalThis, 'Node');
+beforeAll(() => {
+    Object.defineProperty(globalThis, 'Node', {
+        configurable: true,
+        value: { ELEMENT_NODE: 1 }
+    });
+});
+afterAll(() => {
+    if (originalNode) {
+        Object.defineProperty(globalThis, 'Node', originalNode);
+    }
+    else {
+        delete globalThis.Node;
+    }
+});
+describe('DomeManipulator.replaceAllChildrenAsync', () => {
+    async function expectLastQueuedReplacement(animationForHide, animationForShow) {
+        const container = new FakeElement();
+        const existing = new FakeElement();
+        const first = new FakeElement();
+        const second = new FakeElement();
+        container.appendChild(existing);
+        await Promise.all([
+            DomeManipulator.replaceAllChildrenAsync(asElement(container), asElement(first), animationForHide, animationForShow),
+            DomeManipulator.replaceAllChildrenAsync(asElement(container), asElement(second), animationForHide, animationForShow)
+        ]);
+        expect(container.childNodes).toEqual([second]);
+    }
+    it('serializes two concurrent replacements without animations', async () => {
+        await expectLastQueuedReplacement();
+    });
+    it('serializes concurrent replacements with a hide animation', async () => {
+        await expectLastQueuedReplacement(animation('hide'));
+    });
+    it('serializes concurrent replacements with a show animation', async () => {
+        await expectLastQueuedReplacement(undefined, animation('show'));
+    });
+    it('serializes concurrent replacements with hide and show animations', async () => {
+        await expectLastQueuedReplacement(animation('hide'), animation('show'));
+    });
+    it('runs replacements on different containers independently', async () => {
+        const slowContainer = new FakeElement();
+        const fastContainer = new FakeElement();
+        const oldSlowChild = new FakeElement();
+        const slowChild = new FakeElement();
+        const fastChild = new FakeElement();
+        slowContainer.appendChild(oldSlowChild);
+        let slowReplacementFinished = false;
+        const slowReplacement = DomeManipulator.replaceAllChildrenAsync(asElement(slowContainer), asElement(slowChild), { cssClassName: 'hide', timeMs: 30 }).then(() => {
+            slowReplacementFinished = true;
+        });
+        await waitAsync(1);
+        await DomeManipulator.replaceAllChildrenAsync(asElement(fastContainer), asElement(fastChild));
+        expect(fastContainer.childNodes).toEqual([fastChild]);
+        expect(slowReplacementFinished).toBe(false);
+        expect(slowContainer.childNodes).toEqual([oldSlowChild]);
+        await slowReplacement;
+    });
+    it('does not let a failed replacement block a later replacement', async () => {
+        const container = new FakeElement();
+        const failingChild = new FakeElement();
+        const successfulChild = new FakeElement();
+        failingChild.throwOnAppend = true;
+        const failedReplacement = DomeManipulator.replaceAllChildrenAsync(asElement(container), asElement(failingChild));
+        const queuedReplacement = DomeManipulator.replaceAllChildrenAsync(asElement(container), asElement(successfulChild));
+        await expect(failedReplacement).rejects.toThrow('append failed');
+        await queuedReplacement;
+        expect(container.childNodes).toEqual([successfulChild]);
+    });
+});
+class ScheduledTestComponent extends DomeComponent {
+    updateCount = 0;
+    activeUpdates = 0;
+    maximumActiveUpdates = 0;
+    updateBehavior = async () => undefined;
+    render() {
+        return {};
+    }
+    async updateAsync() {
+        this.updateCount++;
+        this.activeUpdates++;
+        this.maximumActiveUpdates = Math.max(this.maximumActiveUpdates, this.activeUpdates);
+        try {
+            await this.updateBehavior();
+        }
+        finally {
+            this.activeUpdates--;
+        }
+    }
+}
+describe('DomeComponent.scheduleUpdate', () => {
+    it('debounces repeated requests made before an update starts', async () => {
+        const component = new ScheduledTestComponent({}, null);
+        await Promise.all([
+            component.scheduleUpdate(),
+            component.scheduleUpdate(),
+            component.scheduleUpdate()
+        ]);
+        expect(component.updateCount).toBe(1);
+    });
+    it('coalesces requests during an update into exactly one follow-up update', async () => {
+        const component = new ScheduledTestComponent({}, null);
+        const firstUpdate = deferred();
+        component.updateBehavior = () => component.updateCount === 1
+            ? firstUpdate.promise
+            : Promise.resolve();
+        const initialSchedule = component.scheduleUpdate();
+        await waitForAsync(() => component.updateCount === 1);
+        component.scheduleUpdate();
+        component.scheduleUpdate();
+        component.scheduleUpdate();
+        await waitAsync(10);
+        firstUpdate.resolve();
+        await initialSchedule;
+        expect(component.updateCount).toBe(2);
+    });
+    it('never runs scheduled updates concurrently for one component', async () => {
+        const component = new ScheduledTestComponent({}, null);
+        const firstUpdate = deferred();
+        component.updateBehavior = () => component.updateCount === 1
+            ? firstUpdate.promise
+            : Promise.resolve();
+        const initialSchedule = component.scheduleUpdate();
+        await waitForAsync(() => component.updateCount === 1);
+        component.scheduleUpdate();
+        await waitAsync(10);
+        expect(component.maximumActiveUpdates).toBe(1);
+        firstUpdate.resolve();
+        await initialSchedule;
+        expect(component.maximumActiveUpdates).toBe(1);
+    });
+    it('allows subsequent scheduled updates after updateAsync rejects', async () => {
+        const component = new ScheduledTestComponent({}, null);
+        const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        component.updateBehavior = async () => {
+            if (component.updateCount === 1) {
+                throw new Error('update failed');
+            }
+        };
+        try {
+            await component.scheduleUpdate();
+            await component.scheduleUpdate();
+        }
+        finally {
+            consoleError.mockRestore();
+        }
+        expect(component.updateCount).toBe(2);
+        expect(component.maximumActiveUpdates).toBe(1);
+    });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
     "sideEffects": false,
     "name": "@lexriver/dome",
-    "version": "2.0.0",
+    "version": "2.0.2",
     "description": "DOM manipulator",
     "type": "module",
     "exports": "./out/src/index.mjs",

package/src/DomeComponent.mts

@@ -10,6 +10,8 @@ interface InternalAttrs{
 }
 export abstract class DomeComponent<Attrs>{
     public rootElement!:Element|HTMLElement
+    private updateInProgress = false
+    private updateRequested = false
     constructor(
         public attrs:Attrs & InternalAttrs, 
         public children:any
@@ -48,9 +50,28 @@ export abstract class DomeComponent<Attrs>{
         this.afterUpdate()
         
     }
-    scheduleUpdate = debounce(() => {
-        this.updateAsync()
-    }, 5)
+    private async runScheduledUpdateAsync() {
+        if(this.updateInProgress){
+            this.updateRequested = true
+            return
+        }
+
+        this.updateInProgress = true
+        try {
+            do {
+                this.updateRequested = false
+                try {
+                    await this.updateAsync()
+                } catch(error) {
+                    console.error('DomeComponent: scheduled update failed', error)
+                }
+            } while(this.updateRequested)
+        } finally {
+            this.updateInProgress = false
+        }
+    }
+
+    scheduleUpdate = debounce(() => this.runScheduledUpdateAsync(), 5)
 
     protected afterUpdate(){
 

package/src/DomeManipulator.mts

@@ -6,6 +6,8 @@ import { Animation } from './Animation.mjs'
 
 export type CssClass = {[key:string]:boolean|ObservableVariable<boolean>} | string[] | string
 
+const replacementPromiseByElement = new WeakMap<Element, Promise<void>>()
+
 export namespace DomeManipulator {
 
     export async function hideElementAsync(element: Element, animation?:Animation) {
@@ -134,8 +136,8 @@ export namespace DomeManipulator {
             forEachChildrenOf(element, (child) => child.nodeType == Node.ELEMENT_NODE && (child as Element).classList.add(animation.cssClassName))
             //console.log('##', 'wait ms', animation.timeMs)
             await Async.waitMsAsync(animation.timeMs)
-            //console.log('##', 'removing children', element.childNodes)
-            forEachChildrenOf(element, (child) => child.remove())
+            // Take a snapshot because childNodes is live and shrinks as nodes are removed.
+            Array.from(element.childNodes).forEach(child => child.remove())
             //console.log('##', 'done')
         }
 
@@ -172,26 +174,35 @@ export namespace DomeManipulator {
     }
 
 
+    /**
+     * Replacements for the same container run in call order. A rejected replacement does
+     * not block the queue, and replacements for different containers remain independent.
+     */
     export async function replaceAllChildrenAsync(
-        containerElement: Element, 
-        childrenToInsert: Element | Element[] | DocumentFragment | Text | string | null | undefined, 
-        animationForHide?:Animation, 
+        containerElement: Element,
+        childrenToInsert: Element | Element[] | DocumentFragment | Text | string | null | undefined,
+        animationForHide?:Animation,
         animationForShow?:Animation
     ) {
-        //await removeAllChildrenAsync(containerElement, animationForHide)
+        const previousReplacement = replacementPromiseByElement.get(containerElement)
+        const replacement = (previousReplacement ?? Promise.resolve())
+            .catch(() => undefined)
+            .then(async () => {
+                if(containerElement.childNodes.length>0){
+                    await removeAllChildrenAsync(containerElement, animationForHide)
+                }
+                await appendChildrenAsync(containerElement, childrenToInsert, animationForShow)
+            })
 
-        if(containerElement.childNodes.length>0){
-            await removeAllChildrenAsync(containerElement, animationForHide) 
-        }
+        replacementPromiseByElement.set(containerElement, replacement)
 
-        // while(containerElement.childNodes.length>0){
-        //     await removeAllChildrenAsync(containerElement, animationForHide) // can be executed more than once! TODO: why?
-        // }
-        // if(containerElement.children.length>0) {
-        //     console.error('DomeManipulator: replaceAllChildenrAsync() failed:', 'containerElement.children.length=', containerElement.children.length, 'children=', containerElement.children, 'containerElement=', containerElement, 'animationForHide=', animationForHide)
-        //     throw new Error()
-        // }
-        await appendChildrenAsync(containerElement, childrenToInsert, animationForShow)    
+        try {
+            await replacement
+        } finally {
+            if(replacementPromiseByElement.get(containerElement) === replacement){
+                replacementPromiseByElement.delete(containerElement)
+            }
+        }
     }
 
 

package/src/DomeRouter.mts

@@ -3,9 +3,10 @@ import { DomeManipulator } from "./DomeManipulator.mjs"
 // const filename = '[DomeRouter]'
 
 export type RouteAction = (
-    params:{[key:string]:string}, 
+    params:{[key:string]:string|number}, 
     url:string,
-    scrollToPreviousPositionAsync:()=>Promise<void>
+    scrollToPreviousPositionAsync:()=>Promise<void>,
+    query:{[key:string]:string}
     ) => void|Promise<void>
 
 interface Route{
@@ -215,7 +216,20 @@ export namespace DomeRouter {
 
     }
 
+    function parseQueryString(search:string):{[key:string]:string}{
+        const query:{[key:string]:string} = {}
+        if(!search || search[0] !== '?') return query
+        const params = new URLSearchParams(search.substring(1))
+        for(const [key, value] of params.entries()){
+            query[key] = value
+        }
+        return query
+    }
+
     async function executeAsync(url:string = window.location.pathname, scrollToPosition:number){
+        const queryString = window.location.search
+        const query = parseQueryString(queryString)
+        url = url.split('?')[0]  // Strip query params
         //const url = window.location.pathname
         const urlSlices = getRouteSlices(url)
         // urlSlices = show, category, 345
@@ -259,7 +273,7 @@ export namespace DomeRouter {
                     await DomeManipulator.scrollToAsync({
                         pxFromTop: scrollToPosition
                     })
-                })
+                }, query)
             }
         }
         if(countOfFoundRoutes==0 && onNotFoundAction){

package/src/concurrent-updates.test.mts

@@ -0,0 +1,252 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
+import { DomeComponent } from './DomeComponent.mjs'
+import { DomeManipulator } from './DomeManipulator.mjs'
+import type { Animation } from './Animation.mjs'
+
+class FakeElement {
+    readonly nodeType = 1
+    readonly childNodes: FakeElement[] = []
+    readonly classList = {
+        values: new Set<string>(),
+        add: (name:string) => this.classList.values.add(name),
+        remove: (name:string) => this.classList.values.delete(name)
+    }
+    parentNode: FakeElement | null = null
+    throwOnAppend = false
+
+    get firstChild() {
+        return this.childNodes[0] ?? null
+    }
+
+    appendChild(child:FakeElement) {
+        if(child.throwOnAppend){
+            throw new Error('append failed')
+        }
+        child.parentNode = this
+        this.childNodes.push(child)
+        return child
+    }
+
+    remove() {
+        if(!this.parentNode) return
+        const index = this.parentNode.childNodes.indexOf(this)
+        if(index >= 0){
+            this.parentNode.childNodes.splice(index, 1)
+        }
+        this.parentNode = null
+    }
+}
+
+const asElement = (element:FakeElement) => element as unknown as Element
+const animation = (name:string):Animation => ({ cssClassName: name, timeMs: 5 })
+const waitAsync = (timeMs:number) => new Promise<void>(resolve => setTimeout(resolve, timeMs))
+
+async function waitForAsync(condition:() => boolean) {
+    const timeoutAt = Date.now() + 500
+    while(!condition()){
+        if(Date.now() >= timeoutAt){
+            throw new Error('Timed out waiting for condition')
+        }
+        await waitAsync(1)
+    }
+}
+
+function deferred() {
+    let resolve!:() => void
+    const promise = new Promise<void>(resolvePromise => {
+        resolve = resolvePromise
+    })
+    return { promise, resolve }
+}
+
+const originalNode = Object.getOwnPropertyDescriptor(globalThis, 'Node')
+
+beforeAll(() => {
+    Object.defineProperty(globalThis, 'Node', {
+        configurable: true,
+        value: { ELEMENT_NODE: 1 }
+    })
+})
+
+afterAll(() => {
+    if(originalNode){
+        Object.defineProperty(globalThis, 'Node', originalNode)
+    } else {
+        delete (globalThis as { Node?:unknown }).Node
+    }
+})
+
+describe('DomeManipulator.replaceAllChildrenAsync', () => {
+    async function expectLastQueuedReplacement(
+        animationForHide?:Animation,
+        animationForShow?:Animation
+    ) {
+        const container = new FakeElement()
+        const existing = new FakeElement()
+        const first = new FakeElement()
+        const second = new FakeElement()
+        container.appendChild(existing)
+
+        await Promise.all([
+            DomeManipulator.replaceAllChildrenAsync(asElement(container), asElement(first), animationForHide, animationForShow),
+            DomeManipulator.replaceAllChildrenAsync(asElement(container), asElement(second), animationForHide, animationForShow)
+        ])
+
+        expect(container.childNodes).toEqual([second])
+    }
+
+    it('serializes two concurrent replacements without animations', async () => {
+        await expectLastQueuedReplacement()
+    })
+
+    it('serializes concurrent replacements with a hide animation', async () => {
+        await expectLastQueuedReplacement(animation('hide'))
+    })
+
+    it('serializes concurrent replacements with a show animation', async () => {
+        await expectLastQueuedReplacement(undefined, animation('show'))
+    })
+
+    it('serializes concurrent replacements with hide and show animations', async () => {
+        await expectLastQueuedReplacement(animation('hide'), animation('show'))
+    })
+
+    it('runs replacements on different containers independently', async () => {
+        const slowContainer = new FakeElement()
+        const fastContainer = new FakeElement()
+        const oldSlowChild = new FakeElement()
+        const slowChild = new FakeElement()
+        const fastChild = new FakeElement()
+        slowContainer.appendChild(oldSlowChild)
+
+        let slowReplacementFinished = false
+        const slowReplacement = DomeManipulator.replaceAllChildrenAsync(
+            asElement(slowContainer),
+            asElement(slowChild),
+            { cssClassName: 'hide', timeMs: 30 }
+        ).then(() => {
+            slowReplacementFinished = true
+        })
+        await waitAsync(1)
+
+        await DomeManipulator.replaceAllChildrenAsync(asElement(fastContainer), asElement(fastChild))
+
+        expect(fastContainer.childNodes).toEqual([fastChild])
+        expect(slowReplacementFinished).toBe(false)
+        expect(slowContainer.childNodes).toEqual([oldSlowChild])
+        await slowReplacement
+    })
+
+    it('does not let a failed replacement block a later replacement', async () => {
+        const container = new FakeElement()
+        const failingChild = new FakeElement()
+        const successfulChild = new FakeElement()
+        failingChild.throwOnAppend = true
+
+        const failedReplacement = DomeManipulator.replaceAllChildrenAsync(
+            asElement(container),
+            asElement(failingChild)
+        )
+        const queuedReplacement = DomeManipulator.replaceAllChildrenAsync(
+            asElement(container),
+            asElement(successfulChild)
+        )
+
+        await expect(failedReplacement).rejects.toThrow('append failed')
+        await queuedReplacement
+        expect(container.childNodes).toEqual([successfulChild])
+    })
+})
+
+class ScheduledTestComponent extends DomeComponent<{}> {
+    updateCount = 0
+    activeUpdates = 0
+    maximumActiveUpdates = 0
+    updateBehavior:() => Promise<void> = async () => undefined
+
+    protected render():HTMLElement {
+        return {} as HTMLElement
+    }
+
+    override async updateAsync() {
+        this.updateCount++
+        this.activeUpdates++
+        this.maximumActiveUpdates = Math.max(this.maximumActiveUpdates, this.activeUpdates)
+        try {
+            await this.updateBehavior()
+        } finally {
+            this.activeUpdates--
+        }
+    }
+}
+
+describe('DomeComponent.scheduleUpdate', () => {
+    it('debounces repeated requests made before an update starts', async () => {
+        const component = new ScheduledTestComponent({}, null)
+
+        await Promise.all([
+            component.scheduleUpdate(),
+            component.scheduleUpdate(),
+            component.scheduleUpdate()
+        ])
+
+        expect(component.updateCount).toBe(1)
+    })
+
+    it('coalesces requests during an update into exactly one follow-up update', async () => {
+        const component = new ScheduledTestComponent({}, null)
+        const firstUpdate = deferred()
+        component.updateBehavior = () => component.updateCount === 1
+            ? firstUpdate.promise
+            : Promise.resolve()
+
+        const initialSchedule = component.scheduleUpdate()
+        await waitForAsync(() => component.updateCount === 1)
+        component.scheduleUpdate()
+        component.scheduleUpdate()
+        component.scheduleUpdate()
+        await waitAsync(10)
+        firstUpdate.resolve()
+        await initialSchedule
+
+        expect(component.updateCount).toBe(2)
+    })
+
+    it('never runs scheduled updates concurrently for one component', async () => {
+        const component = new ScheduledTestComponent({}, null)
+        const firstUpdate = deferred()
+        component.updateBehavior = () => component.updateCount === 1
+            ? firstUpdate.promise
+            : Promise.resolve()
+
+        const initialSchedule = component.scheduleUpdate()
+        await waitForAsync(() => component.updateCount === 1)
+        component.scheduleUpdate()
+        await waitAsync(10)
+
+        expect(component.maximumActiveUpdates).toBe(1)
+        firstUpdate.resolve()
+        await initialSchedule
+        expect(component.maximumActiveUpdates).toBe(1)
+    })
+
+    it('allows subsequent scheduled updates after updateAsync rejects', async () => {
+        const component = new ScheduledTestComponent({}, null)
+        const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined)
+        component.updateBehavior = async () => {
+            if(component.updateCount === 1){
+                throw new Error('update failed')
+            }
+        }
+
+        try {
+            await component.scheduleUpdate()
+            await component.scheduleUpdate()
+        } finally {
+            consoleError.mockRestore()
+        }
+
+        expect(component.updateCount).toBe(2)
+        expect(component.maximumActiveUpdates).toBe(1)
+    })
+})