pv module (v0.3.x)

pv handles DOM creation and keyboard events.

import { pv } from "@page-proxy/pp";

onElementCreated(func, targetNode, observerOptions)

Creates an ElementCreatedObserver (a child class of the built-in JavaScript MutationObserver) and starts it immediately.

Defaults:

• targetNode (optional): document.body || document.documentElement
• observerOptions (optional): { childList: true, subtree: true }

What it does:

• watches for added nodes
• invokes func for each added element plus its descendant elements
• runs an immediate first pass on the target subtree

const observer = pv.onElementCreated((el) => {
    if (el instanceof HTMLElement && el.matches("[data-toast]")) {
        const text = el.textContent ? el.textContent.trim() : "";
        console.log("Toast:", text);
    }
});

ElementCreatedObserver also provides:

• runOnTargetNode() to manually re-scan current target subtree

observer.runOnTargetNode();
observer.disconnect();

onKeyPressed(keys, func, options)

Runs func when a key combo matches.

Options:

• keyAction?: ("press" | "release")[] (default ["press"])
• cancel?: boolean (default false, truthy values prevent default browser behavior)

Returns a cleanup function that removes the event listeners.

const stop = pv.onKeyPressed(
    "shift+x",
    () => {
        console.log("Shift+X pressed");
    },
    {
        keyAction: ["press", "release"],
    },
);

// Later:
stop();

pressKey(keys, options)

Simulates keyboard events programatically.

Options:

• keyAction?: ("press" | "release")[] (default ["press"])
• cancel?: boolean (default false, truthy values call preventDefault() on the simulated event)

pv.pressKey("shift+x", {
    keyAction: ["press", "release"],
});

sleep(ms)

Returns a Promise that resolves after ms milliseconds.

await pv.sleep(250);

awaitAnimation()

Returns a Promise that resolves on the next animation frame.

await pv.awaitAnimation();

awaitMicrotask()

Returns a Promise that resolves in the next microtask.

await pv.awaitMicrotask();

Always use await when calling these Promise-returning helpers.