@studiometa/js-toolkit 3.9.0 → 4.0.0-alpha.1

package/dist/subpaths/withDrag.js

@@ -1,6 +1,2 @@
-import { withDrag, withDrag as withDrag2 } from "../decorators/withDrag.js";
-export {
-  withDrag2 as default,
-  withDrag
-};
-//# sourceMappingURL=withDrag.js.map
+import { withDrag } from "../services/drag.js";
+export { withDrag as default, withDrag };

package/dist/subpaths/withInView.d.ts

@@ -0,0 +1,2 @@
+import { withInView } from "../services/in-view.js";
+export { withInView as default, withInView };

package/dist/subpaths/withInView.js

@@ -0,0 +1,2 @@
+import { withInView } from "../services/in-view.js";
+export { withInView as default, withInView };

package/dist/subpaths/withKey.d.ts

@@ -0,0 +1,2 @@
+import { withKey } from "../services/key.js";
+export { withKey as default, withKey };

package/dist/subpaths/withKey.js

@@ -0,0 +1,2 @@
+import { withKey } from "../services/key.js";
+export { withKey as default, withKey };

package/dist/subpaths/withMutation.d.ts

@@ -1 +1,2 @@
-export { withMutation, withMutation as default } from '../decorators/withMutation.js';
+import { withMutation } from "../services/mutation.js";
+export { withMutation as default, withMutation };

package/dist/subpaths/withMutation.js

@@ -1,6 +1,2 @@
-import { withMutation, withMutation as withMutation2 } from "../decorators/withMutation.js";
-export {
-  withMutation2 as default,
-  withMutation
-};
-//# sourceMappingURL=withMutation.js.map
+import { withMutation } from "../services/mutation.js";
+export { withMutation as default, withMutation };

package/dist/subpaths/withPointer.d.ts

@@ -0,0 +1,2 @@
+import { withPointer } from "../services/pointer.js";
+export { withPointer as default, withPointer };

package/dist/subpaths/withPointer.js

@@ -0,0 +1,2 @@
+import { withPointer } from "../services/pointer.js";
+export { withPointer as default, withPointer };

package/dist/subpaths/withRaf.d.ts

@@ -0,0 +1,2 @@
+import { withRaf } from "../services/raf.js";
+export { withRaf as default, withRaf };

package/dist/subpaths/withRaf.js

@@ -0,0 +1,2 @@
+import { withRaf } from "../services/raf.js";
+export { withRaf as default, withRaf };

package/dist/subpaths/withResize.d.ts

@@ -0,0 +1,2 @@
+import { withResize } from "../services/resize.js";
+export { withResize as default, withResize };

package/dist/subpaths/withResize.js

@@ -0,0 +1,2 @@
+import { withResize } from "../services/resize.js";
+export { withResize as default, withResize };

package/dist/subpaths/withScroll.d.ts

@@ -0,0 +1,2 @@
+import { withScroll } from "../services/scroll.js";
+export { withScroll as default, withScroll };

package/dist/subpaths/withScroll.js

@@ -0,0 +1,2 @@
+import { withScroll } from "../services/scroll.js";
+export { withScroll as default, withScroll };

package/dist/subpaths/withScrollProgress.d.ts

@@ -0,0 +1,2 @@
+import { withScrollProgress } from "../services/scroll-progress.js";
+export { withScrollProgress as default, withScrollProgress };

package/dist/subpaths/withScrollProgress.js

@@ -0,0 +1,2 @@
+import { withScrollProgress } from "../services/scroll-progress.js";
+export { withScrollProgress as default, withScrollProgress };

package/dist/subpaths/write.d.ts

@@ -0,0 +1,2 @@
+import { write } from "../decorators.js";
+export { write as default, write };

package/dist/subpaths/write.js

@@ -0,0 +1,2 @@
+import { write } from "../decorators.js";
+export { write as default, write };

package/dist/swap.d.ts

@@ -0,0 +1,45 @@
+//#region src/swap.d.ts
+/**
+ * Named content swap modes.
+ * @link https://js-toolkit-v4.studiometa.dev/api/dom/swap.html
+ */
+declare const SWAP_MODES: {
+  readonly REPLACE: 'replace';
+  readonly PREPEND: 'prepend';
+  readonly APPEND: 'append';
+  readonly MORPH: 'morph';
+};
+/** One of {@link SWAP_MODES}. */
+type SwapMode = (typeof SWAP_MODES)[keyof typeof SWAP_MODES];
+/**
+ * Content for the target. Strings use the target's parsing context; nodes provide their children.
+ *
+ * With `self`, an `Element` is the replacement itself rather than a container:
+ * that is the only way its own attributes reach the page.
+ */
+type SwapContent = string | Element | DocumentFragment;
+/** A wrapper that must invoke the swap mutation exactly once. */
+type SwapWrap = (mutate: () => void) => void | Promise<unknown>;
+interface SwapOptions {
+  /** Defaults to {@link SWAP_MODES.REPLACE}. */
+  mode?: SwapMode;
+  /** Wrap the mutation. Without a wrapper it runs synchronously. */
+  wrap?: SwapWrap;
+  /**
+   * Replace the target element itself, attributes included, instead of its
+   * children. Only `replace` and `morph` can do that — `append` and `prepend`
+   * add to the children by definition and warn when this is set.
+   */
+  self?: boolean;
+}
+/**
+ * Swap an element's content and wait for observable component lifecycle work.
+ *
+ * @param target The element whose content changes. With `self`, the element itself.
+ * @param content The new content.
+ * @returns Resolves after eager lifecycle work. Conditional mount strategies are not awaited.
+ * @link https://js-toolkit-v4.studiometa.dev/api/dom/swap.html
+ */
+declare function swap(target: Element, content: SwapContent, options?: SwapOptions): Promise<void>;
+//#endregion
+export { SWAP_MODES, SwapContent, SwapMode, SwapOptions, SwapWrap, swap };

package/dist/swap.js

@@ -0,0 +1,84 @@
+import { warn } from "./diagnostics.js";
+import { whenDOMSettled } from "./dom-mutations.js";
+import morphdom from "morphdom";
+//#region src/swap.ts
+/**
+* Named content swap modes.
+* @link https://js-toolkit-v4.studiometa.dev/api/dom/swap.html
+*/
+const SWAP_MODES = {
+	REPLACE: "replace",
+	PREPEND: "prepend",
+	APPEND: "append",
+	MORPH: "morph"
+};
+/**
+* Swap an element's content and wait for observable component lifecycle work.
+*
+* @param target The element whose content changes. With `self`, the element itself.
+* @param content The new content.
+* @returns Resolves after eager lifecycle work. Conditional mount strategies are not awaited.
+* @link https://js-toolkit-v4.studiometa.dev/api/dom/swap.html
+*/
+async function swap(target, content, options = {}) {
+	const { mode = SWAP_MODES.REPLACE, wrap, self = false } = options;
+	const incoming = asContainer(target, content);
+	const replacement = self ? replacementFor(content, incoming) : null;
+	if (self && (mode === SWAP_MODES.APPEND || mode === SWAP_MODES.PREPEND)) warn("swap.self-ignored", `The "${mode}" mode adds to the target's children, so \`self\` was ignored.`, { target });
+	else if (self && !replacement) warn("swap.self-ignored", "The content holds no element to replace the target with.", { target });
+	const knownScripts = new Set(target.querySelectorAll("script"));
+	const mutate = () => {
+		let roots = [target];
+		switch (mode) {
+			case SWAP_MODES.APPEND:
+				target.append(...incoming.childNodes);
+				break;
+			case SWAP_MODES.PREPEND:
+				target.prepend(...incoming.childNodes);
+				break;
+			case SWAP_MODES.MORPH:
+				roots = [replacement ? morphdom(target, replacement) : morphdom(target, incoming, { childrenOnly: true })];
+				break;
+			default: if (replacement) {
+				roots = [replacement];
+				target.replaceWith(replacement);
+			} else target.replaceChildren(...incoming.childNodes);
+		}
+		for (const root of roots) adoptScripts(root, knownScripts);
+	};
+	if (wrap) await wrap(mutate);
+	else mutate();
+	await whenDOMSettled();
+}
+/** Parse strings in a shallow target clone to preserve context-sensitive elements. */
+function asContainer(target, content) {
+	if (content instanceof Element) return content;
+	const container = target.cloneNode(false);
+	if (typeof content === "string") container.innerHTML = content;
+	else container.append(content);
+	return container;
+}
+/**
+* The element that takes the target's place. An `Element` content is that
+* element; anything else contributes its first top-level element.
+*/
+function replacementFor(content, incoming) {
+	return content instanceof Element ? content : incoming.firstElementChild;
+}
+/**
+* Recreate newly inserted scripts so parser-inert scripts run once. Preserved script nodes do not run again.
+*/
+function adoptScripts(root, knownScripts) {
+	const scripts = root instanceof HTMLScriptElement ? [root] : root.querySelectorAll("script");
+	for (const script of scripts) {
+		if (knownScripts.has(script)) continue;
+		const adopted = script.ownerDocument.createElement("script");
+		for (const name of script.getAttributeNames()) adopted.setAttribute(name, script.getAttribute(name));
+		if (script.textContent) adopted.textContent = script.textContent;
+		script.replaceWith(adopted);
+	}
+}
+//#endregion
+export { SWAP_MODES, swap };
+
+//# sourceMappingURL=swap.js.map

package/dist/swap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"swap.js","names":[],"sources":["../src/swap.ts"],"sourcesContent":["import morphdom from 'morphdom';\nimport { warn } from './diagnostics.js';\nimport { whenDOMSettled } from './dom-mutations.js';\n\n/**\n * Named content swap modes.\n * @link https://js-toolkit-v4.studiometa.dev/api/dom/swap.html\n */\nexport const SWAP_MODES = {\n  REPLACE: 'replace',\n  PREPEND: 'prepend',\n  APPEND: 'append',\n  MORPH: 'morph',\n} as const;\n\n/** One of {@link SWAP_MODES}. */\nexport type SwapMode = (typeof SWAP_MODES)[keyof typeof SWAP_MODES];\n\n/**\n * Content for the target. Strings use the target's parsing context; nodes provide their children.\n *\n * With `self`, an `Element` is the replacement itself rather than a container:\n * that is the only way its own attributes reach the page.\n */\nexport type SwapContent = string | Element | DocumentFragment;\n\n/** A wrapper that must invoke the swap mutation exactly once. */\nexport type SwapWrap = (mutate: () => void) => void | Promise<unknown>;\n\nexport interface SwapOptions {\n  /** Defaults to {@link SWAP_MODES.REPLACE}. */\n  mode?: SwapMode;\n  /** Wrap the mutation. Without a wrapper it runs synchronously. */\n  wrap?: SwapWrap;\n  /**\n   * Replace the target element itself, attributes included, instead of its\n   * children. Only `replace` and `morph` can do that — `append` and `prepend`\n   * add to the children by definition and warn when this is set.\n   */\n  self?: boolean;\n}\n\n/**\n * Swap an element's content and wait for observable component lifecycle work.\n *\n * @param target The element whose content changes. With `self`, the element itself.\n * @param content The new content.\n * @returns Resolves after eager lifecycle work. Conditional mount strategies are not awaited.\n * @link https://js-toolkit-v4.studiometa.dev/api/dom/swap.html\n */\nexport async function swap(\n  target: Element,\n  content: SwapContent,\n  options: SwapOptions = {},\n): Promise<void> {\n  const { mode = SWAP_MODES.REPLACE, wrap, self = false } = options;\n  const incoming = asContainer(target, content);\n  const replacement = self ? replacementFor(content, incoming) : null;\n\n  if (self && (mode === SWAP_MODES.APPEND || mode === SWAP_MODES.PREPEND)) {\n    warn(\n      'swap.self-ignored',\n      `The \"${mode}\" mode adds to the target's children, so \\`self\\` was ignored.`,\n      { target },\n    );\n  } else if (self && !replacement) {\n    warn('swap.self-ignored', 'The content holds no element to replace the target with.', {\n      target,\n    });\n  }\n\n  // Track script identity so preserved scripts do not run again.\n  const knownScripts = new Set(target.querySelectorAll('script'));\n\n  const mutate = () => {\n    // Whatever ends up in the document, so its new scripts run exactly once.\n    let roots: Element[] = [target];\n\n    switch (mode) {\n      case SWAP_MODES.APPEND:\n        target.append(...incoming.childNodes);\n        break;\n      case SWAP_MODES.PREPEND:\n        target.prepend(...incoming.childNodes);\n        break;\n      case SWAP_MODES.MORPH:\n        // `childrenOnly` preserves the target and its attributes; `self` is the\n        // opposite ask, so the replacement morphs the target itself.\n        roots = [\n          replacement\n            ? (morphdom(target, replacement) as Element)\n            : (morphdom(target, incoming, { childrenOnly: true }) as Element),\n        ];\n        break;\n      default:\n        if (replacement) {\n          roots = [replacement];\n          target.replaceWith(replacement);\n        } else {\n          target.replaceChildren(...incoming.childNodes);\n        }\n    }\n\n    for (const root of roots) {\n      adoptScripts(root, knownScripts);\n    }\n  };\n\n  if (wrap) {\n    await wrap(mutate);\n  } else {\n    mutate();\n  }\n\n  await whenDOMSettled();\n}\n\n/** Parse strings in a shallow target clone to preserve context-sensitive elements. */\nfunction asContainer(target: Element, content: SwapContent): Element {\n  if (content instanceof Element) {\n    return content;\n  }\n\n  const container = target.cloneNode(false) as Element;\n  if (typeof content === 'string') {\n    container.innerHTML = content;\n  } else {\n    container.append(content);\n  }\n  return container;\n}\n\n/**\n * The element that takes the target's place. An `Element` content is that\n * element; anything else contributes its first top-level element.\n */\nfunction replacementFor(content: SwapContent, incoming: Element): Element | null {\n  return content instanceof Element ? content : incoming.firstElementChild;\n}\n\n/**\n * Recreate newly inserted scripts so parser-inert scripts run once. Preserved script nodes do not run again.\n */\nfunction adoptScripts(root: Element, knownScripts: ReadonlySet<HTMLScriptElement>): void {\n  // `self` can put a script in the document as the root rather than under one.\n  const scripts = root instanceof HTMLScriptElement ? [root] : root.querySelectorAll('script');\n\n  for (const script of scripts) {\n    if (knownScripts.has(script)) {\n      continue;\n    }\n\n    const adopted = script.ownerDocument.createElement('script');\n    for (const name of script.getAttributeNames()) {\n      adopted.setAttribute(name, script.getAttribute(name) as string);\n    }\n    if (script.textContent) {\n      adopted.textContent = script.textContent;\n    }\n    script.replaceWith(adopted);\n  }\n}\n"],"mappings":";;;;;;;;AAQA,MAAa,aAAa;CACxB,SAAS;CACT,SAAS;CACT,QAAQ;CACR,OAAO;AACT;;;;;;;;;AAqCA,eAAsB,KACpB,QACA,SACA,UAAuB,CAAC,GACT;CACf,MAAM,EAAE,OAAO,WAAW,SAAS,MAAM,OAAO,UAAU;CAC1D,MAAM,WAAW,YAAY,QAAQ,OAAO;CAC5C,MAAM,cAAc,OAAO,eAAe,SAAS,QAAQ,IAAI;CAE/D,IAAI,SAAS,SAAS,WAAW,UAAU,SAAS,WAAW,UAC7D,KACE,qBACA,QAAQ,KAAK,iEACb,EAAE,OAAO,CACX;MACK,IAAI,QAAQ,CAAC,aAClB,KAAK,qBAAqB,4DAA4D,EACpF,OACF,CAAC;CAIH,MAAM,eAAe,IAAI,IAAI,OAAO,iBAAiB,QAAQ,CAAC;CAE9D,MAAM,eAAe;EAEnB,IAAI,QAAmB,CAAC,MAAM;EAE9B,QAAQ,MAAR;GACE,KAAK,WAAW;IACd,OAAO,OAAO,GAAG,SAAS,UAAU;IACpC;GACF,KAAK,WAAW;IACd,OAAO,QAAQ,GAAG,SAAS,UAAU;IACrC;GACF,KAAK,WAAW;IAGd,QAAQ,CACN,cACK,SAAS,QAAQ,WAAW,IAC5B,SAAS,QAAQ,UAAU,EAAE,cAAc,KAAK,CAAC,CACxD;IACA;GACF,SACE,IAAI,aAAa;IACf,QAAQ,CAAC,WAAW;IACpB,OAAO,YAAY,WAAW;GAChC,OACE,OAAO,gBAAgB,GAAG,SAAS,UAAU;EAEnD;EAEA,KAAK,MAAM,QAAQ,OACjB,aAAa,MAAM,YAAY;CAEnC;CAEA,IAAI,MACF,MAAM,KAAK,MAAM;MAEjB,OAAO;CAGT,MAAM,eAAe;AACvB;;AAGA,SAAS,YAAY,QAAiB,SAA+B;CACnE,IAAI,mBAAmB,SACrB,OAAO;CAGT,MAAM,YAAY,OAAO,UAAU,KAAK;CACxC,IAAI,OAAO,YAAY,UACrB,UAAU,YAAY;MAEtB,UAAU,OAAO,OAAO;CAE1B,OAAO;AACT;;;;;AAMA,SAAS,eAAe,SAAsB,UAAmC;CAC/E,OAAO,mBAAmB,UAAU,UAAU,SAAS;AACzD;;;;AAKA,SAAS,aAAa,MAAe,cAAoD;CAEvF,MAAM,UAAU,gBAAgB,oBAAoB,CAAC,IAAI,IAAI,KAAK,iBAAiB,QAAQ;CAE3F,KAAK,MAAM,UAAU,SAAS;EAC5B,IAAI,aAAa,IAAI,MAAM,GACzB;EAGF,MAAM,UAAU,OAAO,cAAc,cAAc,QAAQ;EAC3D,KAAK,MAAM,QAAQ,OAAO,kBAAkB,GAC1C,QAAQ,aAAa,MAAM,OAAO,aAAa,IAAI,CAAW;EAEhE,IAAI,OAAO,aACT,QAAQ,cAAc,OAAO;EAE/B,OAAO,YAAY,OAAO;CAC5B;AACF"}

package/dist/test/index.d.ts

@@ -0,0 +1,205 @@
+import { ToolkitDiagnosticDetail } from "../diagnostic-contract.js";
+import { resetRegistry } from "../registry.js";
+//#region src/test/index.d.ts
+/** Options for {@link waitFor}. */
+interface WaitForOptions {
+  /** How long to poll before throwing, in milliseconds. Defaults to `1000`. */
+  timeout?: number;
+  /** The error message thrown on timeout. Replaces the default entirely. */
+  message?: string;
+}
+/**
+ * Wait until every pending mount and every scheduled write has landed.
+ *
+ * The numbers are not arbitrary and are not guessable from the outside. A
+ * component mounts from a `MutationObserver` callback, which the browser
+ * delivers on its own schedule rather than on the microtask that appended the
+ * element; the work the component then queues is drained by the scheduler in
+ * lane order, and a lane may queue into the next one. So neither half is
+ * enough alone: a bare `whenIdle()` can resolve before the observer has even
+ * reported the element, and a bare timer can return between two lanes. Five
+ * rounds of "let the event loop turn, then drain the scheduler" cover a mount
+ * that cascades into children, injections and DOM writes.
+ *
+ * This is the right tool for "the component is up and its writes are done". It
+ * is the wrong tool for a transition's end state — see {@link waitFor}.
+ */
+declare function settle(): Promise<void>;
+/**
+ * Await a number of animation frames.
+ *
+ * Use it when the assertion is about frame-driven work — a `useRaf` service, a
+ * `scheduler.tick()` subscriber, a transition staged one frame at a time — and
+ * the number of frames is part of what is being asserted. When the number is
+ * merely a guess, poll with {@link waitFor} instead.
+ */
+declare function frames(count?: number): Promise<void>;
+/**
+ * Count the animation frames requested while `during` runs.
+ *
+ * **This patches a global.** For the duration of the callback,
+ * `globalThis.requestAnimationFrame` is replaced by a wrapper that increments
+ * a counter and forwards to the original, and the original is put back in a
+ * `finally` — so it is restored whether `during` returns or throws. Nothing
+ * else observes the swap, because the wrapper calls through and returns the
+ * real handle, but two overlapping calls would nest their wrappers, so do not
+ * run them concurrently.
+ *
+ * The assertion it serves is "this did not schedule a frame per event", which
+ * a spy cannot answer: the framework's own scheduler owns the calls, so there
+ * is no seam of the component's to spy on. Assert the count, not the timing —
+ * {@link frames} is for the timing.
+ */
+declare function countRequestedFrames(during: () => Promise<void> | void): Promise<number>;
+/**
+ * Render markup into a wrapper `div`, append it to the document and wait for
+ * the components inside it to be mounted and settled.
+ *
+ * The returned element is the wrapper, never the markup's own root: it is a
+ * stable handle for `querySelector()` calls and it keeps a fragment of several
+ * siblings working. Reach for `.firstElementChild` when the component's own
+ * element is what the test needs.
+ *
+ * ```ts
+ * const root = await mount('<div data-component="Counter"></div>');
+ * const [counter] = getInstances<Counter>('Counter', root);
+ * ```
+ */
+declare function mount(html: string): Promise<HTMLElement>;
+/**
+ * Poll a predicate until it returns something truthy, and return that value.
+ *
+ * It composes as both a guard and a query, because the value comes back:
+ *
+ * ```ts
+ * await waitFor(() => button.classList.contains('is-open'));
+ * const panel = await waitFor(() => root.querySelector('.panel'));
+ * ```
+ *
+ * Any falsy result — `false`, `null`, `undefined`, and also `0` or `''` —
+ * counts as "not yet". Between two attempts the helper both lets a 10ms timer
+ * elapse and drains the scheduler, so it advances the framework's own work
+ * instead of spinning on timers alone. On timeout it throws, with `message` if
+ * one was given.
+ *
+ * **This is how a transition's end state is asserted.** `open()`, `close()`
+ * and the `$watchChildren` callbacks *start* a transition and do not hand it
+ * back, and a kept end state only lands after `nextFrame()`, the `from` and
+ * `active` states, and either a `transitionend` or one more frame. A single
+ * {@link settle} is generous, not deterministic: it passes on a spec run
+ * alone and fails under full-suite load. So assert such a state by polling for
+ * it here, or by awaiting `enter()`/`leave()` where the component returns the
+ * promise.
+ *
+ * **The rule is asymmetric, and the asymmetry is the point.** Never poll for
+ * an *absence*: `leaveTransition()` clears the other direction's `to` class
+ * synchronously, before its first await, so "the class is gone" is already
+ * true when nothing has happened yet and the poll passes for the wrong
+ * reason. Assert a removal directly, after the awaited call that causes it.
+ */
+declare function waitFor<T>(predicate: () => T | false | null | undefined, { timeout, message }?: WaitForOptions): Promise<T>;
+/** What {@link captureDiagnostics} hands back. */
+interface DiagnosticCapture {
+  /** The `code` of every diagnostic seen, in order. */
+  codes: string[];
+  /** The full detail of every diagnostic seen, in the same order. */
+  entries: ToolkitDiagnosticDetail[];
+  /** Detach the listener and let the default sink run again. */
+  stop(): void;
+}
+/**
+ * Collect the diagnostics reported while a test runs, and keep them off the
+ * console.
+ *
+ * **Assert on this, not on the console.** A recovered failure is reported on a
+ * cancelable event, and writing to the console is only that event's default
+ * behaviour — one sink among the several a consumer may install. A test that
+ * spies on `console.warn` asserts on the sink: it passes for a diagnostic
+ * carrying the wrong code, it cannot see the component or the severity, and it
+ * breaks when the sink's wording changes. This helper reads the channel
+ * instead, so `codes` is what the framework actually reported.
+ *
+ * Silencing is not a separate step. Each event is cancelled as it arrives,
+ * which is exactly what suppresses the default sink, so the console stays
+ * clean for as long as the capture is open and no spy is needed:
+ *
+ * ```ts
+ * const log = captureDiagnostics();
+ * registerComponent(Duplicate);
+ * expect(log.codes).toContain('registry.conflict');
+ * log.stop();
+ * ```
+ *
+ * `target` defaults to `document`, which sees everything: a diagnostic is
+ * dispatched on the element it concerns when there is one, and it bubbles.
+ * Pass an element to scope the capture to one subtree — but a diagnostic
+ * reported about a detached element is dispatched on `document` instead, so a
+ * scoped capture will not see it.
+ *
+ * `entries` carries the whole detail — `severity`, `code`, `message`, the
+ * `component` name when one reported it, and `error` on an error-severity
+ * entry — for the cases where the code alone is not the assertion.
+ */
+declare function captureDiagnostics(target?: EventTarget): DiagnosticCapture;
+/** One event {@link recordEvents} saw. */
+interface RecordedEvent {
+  type: string;
+  /** The `detail` of a `CustomEvent`; `undefined` for a platform event. */
+  detail: unknown;
+}
+/** What {@link recordEvents} hands back. */
+interface EventRecording {
+  /** Every matching event seen, in delivery order. */
+  events: RecordedEvent[];
+  /** Detach every listener. */
+  stop(): void;
+}
+/**
+ * Record the named events reaching a target, with the payload each carried.
+ *
+ * The order and the payloads are the assertion a component's contract is made
+ * of — that `open` came before `opened`, and that the second one carried the
+ * height it measured — and neither survives a spy that only counts calls:
+ *
+ * ```ts
+ * const log = recordEvents(root, 'open', 'opened');
+ * await instance.open();
+ * expect(log.events).toEqual([
+ *   { type: 'open', detail: null },
+ *   { type: 'opened', detail: { height: 120 } },
+ * ]);
+ * log.stop();
+ * ```
+ *
+ * Recording types rather than one type keeps a sequence spanning several names
+ * in one array, which is the only place their relative order is visible. A
+ * caller that wants the names alone maps over the result; the reverse is not
+ * possible, so the richer shape is the one that ships.
+ *
+ * `$emit` itself dispatches synchronously, but almost nothing calls it
+ * synchronously: the emit follows a mount, a scheduled write or a transition,
+ * and the call that started that chain has already returned. So **wait for the
+ * count rather than reading it**, with {@link waitFor}:
+ *
+ * ```ts
+ * const log = recordEvents(root, 'ping');
+ * instance.start();
+ * await waitFor(() => log.events.length === 2);
+ * ```
+ *
+ * Because component events bubble, the target is usually the wrapper
+ * {@link mount} returned rather than the component's own element — which is
+ * also how a test sees the events of a child it never looked up.
+ */
+declare function recordEvents(target: EventTarget, ...types: string[]): EventRecording;
+/**
+ * Empty the document body and wait for the unmounts to land.
+ *
+ * Removing an element is observed like adding one, so the teardown a component
+ * registered runs after the same delivery latency. Call it from an `afterEach`
+ * hook: a component left mounted keeps its service subscriptions and leaks
+ * into the next test.
+ */
+declare function resetDom(): Promise<void>;
+//#endregion
+export { DiagnosticCapture, EventRecording, RecordedEvent, WaitForOptions, captureDiagnostics, countRequestedFrames, frames, mount, recordEvents, resetDom, resetRegistry, settle, waitFor };