import { type Digest, type ObservationProfile, type Recipe, type StepClock, type Tier } from '@variance-authority/core/format';
/**
 * Hold the page still *before the subject is observed*, not before it is painted.
 *
 * ## The gap this closes
 *
 * The computed-style allowlist excludes `animation-*` and `transition-*` on the
 * stated grounds that a snapshot is taken "at a declared settle point with
 * animation disabled". Nothing disabled it. `transform`, `opacity`, `filter`,
 * `color` and every geometric longhand *are* admitted, so a subject collected
 * 120ms into a 300ms fade produced a snapshot of a frame no reviewer would
 * recognise — and the next run, collected 180ms in, reported a change with a
 * component name and a source file attached.
 *
 * That is worse than an unexplained pixel diff, because it is credible. A
 * reviewer reads "Card moved at `opacity`, `src/Card.tsx:14`" and looks for the
 * edit. There is no edit. It is the row `flakiness.md` marks *absorbed by
 * nothing* and the one a first run is most likely to hit.
 *
 * ## Where the damage lands, and why it is invisible
 *
 * One `<style>` element, marked with {@link STABILIZE_ATTRIBUTE} and skipped by
 * `indexStyleSheets` — so the tool's own rules never enter a capture, never
 * match a node, and never appear in anybody's attribution. Deleting this module
 * deletes the intervention completely, which is the property the intervention
 * vocabulary claims for the cheapest tier of damage and would not have had if
 * the sheet were collected like any other.
 *
 * What *does* survive into the capture is the effect: `transform` reads its
 * first frame rather than a frame off the clock. That is the point, and it is
 * why {@link stabilizeForObservation} returns a digest for
 * `EnvironmentInputs.stabilization`. A baseline collected untouched and a run
 * collected held still are two baselines, not a diff — the alternative is one
 * confident wrong answer per animated node.
 */
/**
 * Marks the sheet this module injects, so the collector can skip it.
 *
 * A `data-` prefix because it is an attribute on a real element in the
 * adopter's page, and the page belongs to them. Exported because the skip and
 * the injection must not drift: two spellings of this string is a stabilization
 * sheet collected as content, which shows up as `*` matching every node in the
 * subject.
 */
export declare const STABILIZE_ATTRIBUTE = "data-va-stabilize";
export interface Stabilized {
    /** Ids actually applied, in recipe order. Empty when the tier could observe none. */
    readonly ids: readonly string[];
    /**
     * `EnvironmentInputs.stabilization`, or `undefined` when nothing was applied.
     *
     * Undefined rather than the digest of an empty recipe: *observed untouched* is
     * a state the environment key should record as absent, and an empty-list
     * digest is a confident-looking value that says the opposite.
     */
    readonly digest: Digest | undefined;
    /**
     * The media features the held recipe made the browser report, for
     * `collect`'s `features`, or absent when it made it report none.
     *
     * Collection resolves `@media` against declared features rather than asking
     * the browser, so a preference the driver emulated has to be declared here or
     * it is read as unknown. Only a trick the host drove counts.
     */
    readonly features?: Readonly<Record<string, string>>;
    /** Remove the injected sheet. Rarely wanted — see {@link stabilizeForObservation}. */
    readonly release: () => void;
    /**
     * Give focus back to the element `no-focus` took it from.
     *
     * A host that reads a page somebody goes on using — a test that types after
     * it observes, an agent that keeps working in its browser — calls this once
     * the reading, and any photograph of it, is taken. Does nothing when the
     * recipe held no `no-focus`, when nothing was focused, when the element has
     * left the document, or when something else took focus in the meantime.
     */
    readonly refocus: () => void;
}
export interface StabilizeOptions {
    /** Defaults to {@link COLLECT_RECIPE}. */
    readonly recipe?: Recipe;
    /** Defaults to whichever profile the host can support. */
    readonly profile?: ObservationProfile;
    /**
     * The rung this *reading* stands on, when it is higher than the profile's.
     *
     * {@link tierOfProfile} caps at `layout` on purpose: a collection is a
     * reading, and a machine that could photograph is not a reason to charge a
     * reading for a caret nobody is going to photograph. That reasoning holds for
     * every collection taken on its own — and fails for exactly one caller, the
     * in-place capture path, which reads the subject and then screenshots *the
     * same live document*. There the caret will be photographed, by this reading's
     * own sheet, moments later.
     *
     * Without this, `hideCaret` sits in {@link COLLECT_RECIPE} and is filtered out
     * of every call: a focused text input is photographed with its caret blinking,
     * and a suite sees a one-pixel column appear and disappear across runs with no
     * component and no cause attached to it. The raster path meanwhile declines to
     * ask the driver to hide the caret, on the stated grounds that this sheet
     * already governs it.
     *
     * Never raises what the profile can observe — jsdom asking for `raster` still
     * gets jsdom's tier — because a rung is a claim about the host and this is a
     * claim about the reading.
     */
    readonly tier?: Tier;
    /**
     * The driver tricks the host applied to this page before it was read.
     *
     * Reduced motion, a fixed clock and the pointer off the page are applied by
     * the browser driver, not by anything this document can do to itself. A trick
     * in the recipe that the host did not drive is left out of the ids and the
     * digest, so a reading never records a hold it did not have. Absent means
     * the host drove nothing.
     */
    readonly driven?: readonly string[];
    /**
     * Where each wait is taken as a step: the recipe's settles by id, and
     * `frames` for the two frames after a new sheet. Absent takes nothing.
     */
    readonly steps?: StepClock;
}
/** What a host asks of {@link stabilizeAsRequested}, in the shape it crosses into the page. */
export interface StabilizeRequest {
    /** The recipe by id. Absent is the collection recipe. */
    readonly stabilize?: readonly string[];
    /** As {@link StabilizeOptions.tier}. */
    readonly tier?: Tier;
    /** As {@link StabilizeOptions.driven}. */
    readonly driven?: readonly string[];
}
/**
 * {@link stabilizeForObservation} for a request that reached the page as data.
 *
 * A page agent receives the recipe as ids, because an intervention carries
 * functions and cannot be serialized. Rejects on an id nothing answers to, as
 * `recipeOf` throws.
 */
export declare function stabilizeAsRequested(document: Document, request: StabilizeRequest, steps?: StepClock): Promise<Stabilized>;
/**
 * Apply a collection recipe to a live document.
 *
 * **Idempotent by element, not by call.** The sheet is found and rewritten
 * rather than appended, because a session that collects thirty subjects through
 * one document would otherwise accumulate thirty identical stylesheets — each
 * one more sheet for every later subject's index to walk past.
 *
 * The sheet is deliberately *left in place*. Removing it between subjects would
 * restart every animation the moment the next subject is about to be read,
 * which is the failure this exists to prevent, run once per subject. `release`
 * exists for a caller who owns the page and wants it back.
 */
export declare function stabilizeForObservation(document: Document, options?: StabilizeOptions): Promise<Stabilized>;
//# sourceMappingURL=stabilize.d.ts.map