@jbrowse/capture 5.0.0-beta.1 → 5.0.0-beta.10

package/esm/version.d.ts

@@ -0,0 +1 @@
+export declare const version = "5.0.0-beta.10";

package/esm/version.js

@@ -0,0 +1 @@
+export const version = '5.0.0-beta.10';

package/esm/waits.d.ts

@@ -1,214 +1,35 @@
 import type { ElementHandle, Page } from 'puppeteer';
-export declare const delay: (ms: number) => Promise<void>;
-export declare const LOADING_OVERLAY = "[data-testid=\"loading-overlay\"]";
-/**
- * The whole readiness contract, in one selector.
- *
- * `AppReadyMarker` renders it from the session: it reads `ready` when no view
- * is resolving an assembly and no display is fetching, and `loading` whenever
- * one is. Waiting for it is the entire job — everything else in this module is
- * either a narrower question (has THIS display painted) or a fallback for a
- * deployment too old to publish it.
- *
- * It is POSITIVE, which is the property that matters. Every other signal here
- * is an absence, and an absence is equally true of an app that has not started:
- * measured on a two-track session, the gap between "the session holds the
- * tracks" and "the first loading indicator appears" is about a second, and a
- * capture taken in it is a picture of an empty browser.
- */
-export declare const APP_READY = "[data-app-phase=\"ready\"]";
-export declare function waitForLoadingComplete(page: Page, { timeout, waitForDownloads, }?: {
-    timeout?: number;
-    waitForDownloads?: boolean;
-}): Promise<boolean>;
-/**
- * Wait until nothing on the page is in flight.
- *
- * Every signal it reads is one the app publishes deliberately — the loading
- * overlay, `data-busy`, the display and view phases, and each display's own
- * status message on the session model. See `isPageBusyInPage`.
- *
- * It used to scan rendered text for /^(loading|rendering|computing)/ and resolve
- * `getComputedStyle` on each match to decide whether it was on screen. That is a
- * heuristic over a rendering: it broke on a reworded or translated message, it
- * needed the visibility check only because the loading overlay keeps the word
- * "Loading" in the DOM at `opacity: 0`, and an unset opacity parses to zero
- * outside a full layout engine, which reads every ordinary element as hidden. A
- * component that wants to be waited for now says so with an attribute.
- *
- * Best-effort: a view genuinely stuck loading would otherwise burn the whole
- * timeout, so this reports false rather than throwing and the caller decides.
- */
-export declare function waitForQuiescent(page: Page, { timeout }?: {
+interface WaitOptions {
     timeout?: number;
-}): Promise<boolean>;
+}
+/** The app's own verdict: no view is resolving an assembly, no display is fetching. */
+export declare const APP_READY = "[data-app-phase=\"ready\"]";
+/** Displays that have not yet drawn anything. */
 export declare const PENDING_DISPLAYS = "[data-display-drawn=\"false\"]";
-/**
- * `page.waitForSelector`, with the display census in the timeout.
- *
- * The waits below are best-effort and hand their outcome back as a boolean, so
- * a caller can say what was still unsettled. A *selector* wait is the opposite
- * shape — it throws, and it runs FIRST, before any of them: a capture whose
- * display never paints dies here on puppeteer's `TimeoutError`, which names the
- * selector and nothing else, and the census that would have named the display
- * runs later or not at all.
- *
- * So the census runs on the way out. It is re-read from the DOM here rather
- * than taken off a handle the wait held: a handle to an element that has since
- * re-rendered throws `Node is detached from document`, which is how the first
- * attempt at this turned four diagnosable timeouts into nine opaque puppeteer
- * errors (reverted in 28c6ee6d90).
- *
- * What it reports is the phase, and that is the part a longer timeout cannot
- * substitute for: `loading` is a slow fetch, `error` is a display that has
- * finished badly and is showing a banner, and `ready` is a display claiming it
- * finished without drawing — a bug in the display rather than in the wait.
- *
- * An EMPTY census is the other answer, and `tooLarge` / `renderError` are why it
- * is not good news. Those two replace the display's subtree outright, so they
- * publish neither attribute and appear here as nothing at all: a wait on such a
- * display can never resolve and can never be reported. Nothing pending means
- * either that, or a selector that was never a display's.
- */
-export declare function waitForSelectorAttributed(page: Page, selector: string, timeoutMs: number): Promise<ElementHandle>;
-/**
- * The census as one clause, for a message. Best-effort in its own right: a page
- * whose execution context is gone cannot be asked, and saying so is the answer.
- */
-export declare function describePendingDisplaysNow(page: Page): Promise<string>;
+/** A display of this type that has drawn something, possibly mid-fetch. */
 export declare const displayPainted: (testid: string) => string;
-/**
- * The stronger one. `drawn` flips on FIRST paint — an empty canvas with the
- * fetch still in flight satisfies it — so a figure that must show *data* waits
- * on the phase instead.
- */
+/** A display of this type whose fetch has finished. */
 export declare const displaySettled: (testid: string) => string;
-/** One display, by its config's `displayId` rather than by type. */
-export declare const displayById: (displayId: string) => string;
-export declare function waitForDisplaysDone(page: Page, timeoutMs: number): Promise<boolean>;
-export declare function waitForDisplayPhases(page: Page, timeoutMs: number): Promise<boolean>;
-export declare function waitForViewPhases(page: Page, timeoutMs: number): Promise<import("puppeteer").JSHandle<false> | import("puppeteer").JSHandle<true>>;
-/**
- * Everything the app publishes to say it is working, as one selector.
- *
- * All four are attributes a component sets deliberately, which is the whole
- * point: the alternative — scanning rendered text for /^loading/ and resolving
- * `getComputedStyle` to decide whether each match is on screen — makes a
- * reworded message, a translation or an opacity animation change the answer.
- *
- *   `loading-overlay`      the view-level scrim, present in every build
- *   `data-busy`            LoadingEllipses, which is what the app renders
- *                          wherever it tells a user it is working
- *   `data-display-phase`   one display's own fetch, newer builds
- *   `data-view-phase`      a view still resolving its assembly, newer builds
- */
-export declare const BUSY_SELECTOR: string;
 /**
- * Is the app doing anything right now?
- *
- * Serialized into the page, so it declares everything it uses. Two sources: the
- * selector above, and the live session model's own per-display status, which is
- * the only PER-DISPLAY signal a build with no readiness attributes has left.
- * Both are contracts rather than renderings — a model field and a set of data
- * attributes — so neither moves when the UI is restyled.
- *
- * Exported so a test can call the real function rather than a copy of it.
+ * `page.waitForSelector`, whose timeout names each display that had not
+ * painted and the phase it was in.
  */
-export declare function isPageBusyInPage(): boolean;
-/**
- * Wait until the app has been idle for an unbroken stretch.
- *
- * The gate for a build that publishes no readiness attributes, where every
- * other wait in this module is an assertion about an absent selector and so
- * cannot fail. Absence answers "is it working NOW"; a capture needs "has it
- * finished", and the two differ in both directions:
- *
- *   BEFORE the work starts. Measured on jbrowse.org/code/jb2/latest with two
- *   remote tracks: the session reports both tracks open at ~2.5s and the
- *   loading overlay does not go up until ~3.5s. Every absence-based gate passes
- *   during that second, over an app that has drawn nothing.
- *
- *   BETWEEN two pieces of work. A track that finishes one fetch and starts the
- *   next is momentarily idle, and a single-sample gate takes it.
- *
- * Requiring the idle to HOLD closes both without needing to know which signals
- * a given build has. Polled from node rather than in-page: chrome throttles
- * in-page timers and rAF once the tab is not visible, which is the state a
- * headless capture sits in.
- *
- * Returns false on timeout rather than throwing, like its neighbours — the
- * caller decides whether a page that never went quiet is a failure or a slow
- * page worth capturing anyway.
- */
-export declare function waitForQuietPeriod(page: Page, { quietMs, timeout, pollMs, busyWindowMs, }?: {
-    quietMs?: number;
-    timeout?: number;
+export declare function waitForSelectorAttributed(page: Page, selector: string, { timeout }?: WaitOptions): Promise<ElementHandle>;
+type SettleOptions = WaitOptions & {
+    holdMs?: number;
     pollMs?: number;
-    /**
-     * Wait for the app to be seen BUSY before any idle counts, giving up on
-     * that after this long. Zero (the default) accepts idle immediately.
-     *
-     * This is what turns the wait positive. Idle is still an absence, so an app
-     * that has not begun looks exactly like one that has finished — measured on
-     * jbrowse.org/code/jb2/latest, where a chain starting at the session gate
-     * saw an idle page at 1.6s and the tracks did not draw until past 10s.
-     * Seeing the transition INTO work and back out of it is an observation of
-     * the work itself.
-     *
-     * The window is bounded because a page with nothing to fetch never goes
-     * busy at all, and hanging on that would be worse than the race it closes.
-     * Size it above the gap between the session gate passing and the first
-     * indicator appearing, measured at ~1s on that instance.
-     */
-    busyWindowMs?: number;
-}): Promise<boolean>;
+};
 /**
- * Wait for the app to say it has finished.
- *
- * One selector, no chain: `[data-app-phase="ready"]` is rendered by the session
- * itself, so it cannot be satisfied before the app exists. Returns false if the
- * page never publishes it, which is how a caller tells "not ready yet" from "a
- * build too old to have the marker" and falls back.
+ * `waitForAppSettled`, answering with what was still blocking at the timeout,
+ * or undefined once the hold passed.
  */
-export declare function waitForAppReady(page: Page, { timeout }?: {
-    timeout?: number;
-}): Promise<boolean>;
-/** Whether this build publishes the app-level readiness marker at all. */
-export declare function hasAppReadyMarker(page: Page): Promise<boolean>;
+export declare function appSettledBlocker(page: Page, { timeout, holdMs, pollMs, }?: SettleOptions): Promise<string | undefined>;
 /**
- * Wait out work an INTERACTION started: `ready`, and still ready a beat later.
- *
- * The gate for after a click, a keystroke or a resize, where `waitForAppReady`
- * alone is not one. A page that is still LOADING starts at `loading` and the
- * transition into `ready` is the app finishing, so one read of the selector
- * answers it. After an interaction the app is already `ready` — it was finished a
- * moment ago — and stays that way until the click's work registers, so the same
- * read returns instantly, on the pre-click frame.
- *
- * What it replaces is a fixed sleep, which is wrong in both directions and only
- * ever caught in one: too short captures the work in progress, and the figure it
- * produces looks finished, while too long is dead time on every run.
- *
- * **Not "seen busy, then ready"**, which is the obvious shape and was built and
- * measured first. Waiting for `loading` to appear before accepting `ready` needs
- * a cap, since an interaction that only opened a menu never makes the app busy at
- * all — and on the figure spec it was measured against
- * (`search_feature_highlight`) the app was never seen busy either, because that
- * spec's own selector wait had already outlasted the redraw. The busy window then
- * ran to its 2s cap having watched nothing, costing more than the 1.2s sleep it
- * replaced. Requiring the idle to HOLD costs the hold and no more, and catches
- * the same late-starting work.
- *
- * Polled from Node rather than by `page.waitForSelector`, for the reason
- * `waitForQuietPeriod` is: chrome throttles in-page timers and rAF once the tab
- * is not visible, which is exactly the state a headless capture sits in.
- *
- * Falls back to the quiet period on a build too old for the marker, rather than
- * passing instantly. A no-op that reports success is how a spec that dropped its
- * sleep for this ends up capturing the frame the sleep was there to avoid.
+ * Wait until every app on the page has read ready, with nothing loading or
+ * animating, for an unbroken `holdMs`. False on timeout. Right after a
+ * navigation it first waits for the marker to mount; a page that never
+ * publishes `[data-app-phase]` throws, since nothing positive exists to wait
+ * for.
  */
-export declare function waitForAppSettled(page: Page, { timeout, holdMs, pollMs, }?: {
-    timeout?: number;
-    holdMs?: number;
-    pollMs?: number;
-}): Promise<boolean>;
+export declare function waitForAppSettled(page: Page, options?: SettleOptions): Promise<boolean>;
+export {};