@describe-me/core 0.5.1 → 0.5.3

package/README.md

@@ -15,7 +15,7 @@ pnpm add -D @describe-me/core
 ```
 
 All describe-me packages must be on the same version
-([Add it to your project](https://github.com/grzehub/describe-me#add-it-to-your-project)).
+([One version for all packages](https://grzehub.github.io/describe-me/installation.html#lockstep)).
 
 ## Usage
 
@@ -40,9 +40,8 @@ flight and takes a deferred render frame.
 The manifest types live in `@describe-me/core/types`, for tools that want to
 read `.describe-me/manifest.json` themselves. Stored snapshots point into
 `assets/` and `styles/` through `ASSET_URL_PREFIX` and `STYLE_URL_PREFIX`
-([Output directory](https://github.com/grzehub/describe-me#output-directory) in
-the root README). `@describe-me/core/css-references` lists the `url()` and
+([The output directory](https://grzehub.github.io/describe-me/how-it-works.html#storage) in
+the docs). `@describe-me/core/css-references` lists the `url()` and
 `@import` references in CSS text.
 
-See the [root README](https://github.com/grzehub/describe-me#readme) for the
-full picture.
+See the [docs](https://grzehub.github.io/describe-me/) for the full picture.

package/dist/recorder.d.ts

@@ -8,13 +8,14 @@ type Teardown = () => void;
  */
 declare class Recorder {
     /** Which contract this recorder follows, so another copy of core can refuse it. */
-    readonly protocol = 1;
+    readonly protocol = 2;
     private slots;
     private currentGeneration;
     private inFlight;
     private deferred;
     private pending;
     private renderFrame;
+    private aroundWait;
     private component?;
     private startedAt;
     private active;
@@ -28,9 +29,10 @@ declare class Recorder {
      */
     get generation(): number;
     /**
-     * Choose when the render frame is taken, from the next render capture on.
-     * The setup files call it with the plugin's options. A `pending` selector
-     * the DOM rejects falls back to `'lazy'` with a warning.
+     * Choose when the render frame is taken, from the next render capture on,
+     * and what runs around each wait. The setup files call it with the plugin's
+     * options. A `pending` selector the DOM rejects falls back to `'lazy'` with
+     * a warning.
      */
     configure(options: RecorderOptions): void;
     /**
@@ -64,6 +66,7 @@ declare class Recorder {
      */
     private defer;
     private clearDeferred;
+    private waitToSettle;
     private settleThenFill;
     private fill;
 }

package/dist/recorder.js

@@ -9,7 +9,7 @@ import { ANONYMOUS_COMPONENT, } from './types.js';
  * Bump it whenever the contract between the recorder and the adapters or setup
  * files changes: a method or property added, removed or changed in meaning.
  */
-const RECORDER_PROTOCOL = 1;
+const RECORDER_PROTOCOL = 2;
 function isValidSelector(selector) {
     try {
         document.querySelector(selector);
@@ -36,6 +36,7 @@ class Recorder {
     deferred = null;
     pending = null;
     renderFrame = 'eager';
+    aroundWait = (wait) => wait();
     component;
     startedAt = 0;
     active = false;
@@ -63,12 +64,16 @@ class Recorder {
         return this.currentGeneration;
     }
     /**
-     * Choose when the render frame is taken, from the next render capture on.
-     * The setup files call it with the plugin's options. A `pending` selector
-     * the DOM rejects falls back to `'lazy'` with a warning.
+     * Choose when the render frame is taken, from the next render capture on,
+     * and what runs around each wait. The setup files call it with the plugin's
+     * options. A `pending` selector the DOM rejects falls back to `'lazy'` with
+     * a warning.
      */
     configure(options) {
         const renderFrame = options.renderFrame ?? 'eager';
+        if (options.aroundWait !== undefined) {
+            this.aroundWait = options.aroundWait;
+        }
         if (typeof renderFrame === 'object' &&
             typeof document !== 'undefined' &&
             !isValidSelector(renderFrame.pending)) {
@@ -157,7 +162,7 @@ class Recorder {
             return false;
         }
         const generation = this.currentGeneration;
-        await settle();
+        await this.waitToSettle();
         // The test ended, or an interaction took the frame, while this settled.
         if (generation !== this.currentGeneration || this.deferred !== slot) {
             return false;
@@ -215,8 +220,13 @@ class Recorder {
         this.pending?.dispose();
         this.pending = null;
     }
+    // Only the wait runs inside `aroundWait`, so whatever the wrapper changes is
+    // undone before the snapshot and the teardown.
+    waitToSettle() {
+        return this.aroundWait(settle);
+    }
     async settleThenFill(slot, generation) {
-        await settle();
+        await this.waitToSettle();
         if (generation === this.currentGeneration) {
             this.fill(slot);
         }

package/dist/types.d.ts

@@ -49,10 +49,18 @@ export type RenderFrameMode = 'eager' | 'lazy' | {
     pending: string;
     timeout?: number;
 };
+/** Runs one wait of the recorder. It must call `wait` once and resolve after it. */
+export type AroundWait = (wait: () => Promise<void>) => Promise<void>;
 /** Options for `recorder.configure()`. */
 export interface RecorderOptions {
     /** When the render frame is taken. Default: `'eager'`. */
     renderFrame?: RenderFrameMode;
+    /**
+     * Runs each wait of the recorder. It is kept when omitted, so a later
+     * `configure({ renderFrame })` keeps the setup file's wrapper. By default
+     * it runs `wait` as is.
+     */
+    aroundWait?: AroundWait;
 }
 /** Options for `recorder.capture()`. */
 export interface CaptureOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/core",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Recorder and manifest types for describe-me: living component docs from your tests",
   "keywords": [
     "vitest",