@steppy/player 0.0.0-stage → 0.4.0

package/dist/types/steppy-guide.d.ts

@@ -0,0 +1,195 @@
+/**
+ * ``<steppy-guide>`` — Lit-based interactive guide player.
+ *
+ * Public API is HTML attributes + CustomEvents. See the Stage 1 design doc for
+ * the full contract. Implementation notes:
+ *
+ * - Manifest is fetched lazily when ``src`` is set; cached in ``manifest``
+ *   state. ``parseManifest`` does both JSON parsing and Zod validation.
+ * - Coordinates flow capture-space → display-space at one point only:
+ *   ``computeHotspotRect`` (which the cursor animator also uses via
+ *   ``getDisplayScale``). Everything downstream — hotspot button, tooltip,
+ *   cursor target — derives from the same scale, so resizes can never
+ *   produce drift between cursor and hotspot.
+ * - The cursor / ripple / kbd elements live at a fixed position in the
+ *   template so Lit's incremental render doesn't churn them; the animator
+ *   refreshes its DOM refs once on connect.
+ * - Step progression is centralized in ``_advance`` and ``_playCurrentPosition``;
+ *   the rest of the component is rendering.
+ */
+import { LitElement, type PropertyValues } from 'lit';
+import { type AnimatorOptions } from './cursor/animator.js';
+import type { AnimatorFrame } from './cursor/types.js';
+import { DEFAULT_UI_STRINGS, type UiStrings } from './i18n/ui-strings.js';
+import type { CursorMode, TemplateMode } from './manifest/schema.js';
+/** Animator-shaped subset the player actually calls. Tests can plug in a
+ *  stub that skips real timing without owning the full CursorAnimator API. */
+export interface AnimatorLike {
+    setTimings(t: Partial<import('./cursor/types.js').CursorTimings>): void;
+    setStage(stage: HTMLElement): void;
+    refreshDom(): void;
+    hide(): void;
+    abort(): void;
+    travelToTarget(frame: AnimatorFrame, targetIndex: number): Promise<void>;
+    playTargetAction(frame: AnimatorFrame, targetIndex: number): Promise<void>;
+}
+export declare class SteppyGuide extends LitElement {
+    /** Factory hook — overridden in tests to swap in a fast/no-op animator. */
+    static createAnimator: (opts: AnimatorOptions) => AnimatorLike;
+    static styles: import("lit").CSSResult[];
+    src: string;
+    locale: string | null;
+    variant: string | null;
+    autoplay: boolean;
+    startIndex: number;
+    /**
+     * Cursor presentation:
+     * - 'arrow'   (default) animate the arrow + ripple/kbd; hotspot also pulses
+     * - 'hotspot' skip arrow/ripple/kbd; hotspot pulses and user still clicks
+     * - 'off'     skip arrow + hotspot; auto-advance every step after waitAfter
+     * Unset (null) ⇒ fall back to manifest's `cursor.mode`, then 'arrow'.
+     */
+    cursor: CursorMode | null;
+    /**
+     * Presentation template (runtime-switchable viewer setting):
+     * - 'overlay' (default) floating callout pinned to the target
+     * - 'sidebar' left rail with a step timeline + description
+     * - 'inline'  slim bottom caption bar
+     * Resolution: this attribute → persisted localStorage → manifest
+     * ``defaultTemplate`` → 'overlay'. Unknown strings fall through.
+     */
+    template: TemplateMode | null;
+    /** When set, suppress the built-in layout (variant) switcher so a host can
+     *  own the control (the generated Angular toolbar / static page nav drives
+     *  `variant` directly). The locale switcher is unaffected. */
+    hideLayoutSwitcher: boolean;
+    /** Sparse per-locale UI string overrides. Property-only (no attribute). */
+    uiStrings: Partial<Record<string, Partial<UiStrings>>> | undefined;
+    private manifest;
+    private loadError;
+    private currentStepIndex;
+    private currentFrameIndex;
+    private currentTargetIndex;
+    private waitingForInput;
+    private completed;
+    private missCount;
+    private hotspotRect;
+    private tooltipPlacement;
+    private stageSize;
+    /** Resolved presentation template the current render uses. */
+    private _activeTemplate;
+    /** The stage element the ResizeObserver/animator are currently bound to.
+     *  Tracked so a template switch (which relocates the stage) re-attaches. */
+    private _observedStage;
+    /** Furthest step the user has reached. Used to gate ``goTo`` / ``prev``. */
+    private maxReachedStepIndex;
+    private animator;
+    private stageRef;
+    private imgRef;
+    private cursorRef;
+    private rippleRef;
+    private kbdRef;
+    private tooltipRef;
+    private resizeObserver;
+    private autoAdvanceTimer;
+    /** Token bumped on every ``_playCurrentPosition`` call so stale awaits drop. */
+    private playToken;
+    /** Resolved on the user's correct click; the running play awaits this. */
+    private waitForClick;
+    private resolveClick;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(changed: PropertyValues): void;
+    updated(changed: PropertyValues): void;
+    /** Keep the current timeline row visible. The sidebar rail is height-capped
+     *  and scrolls its timeline internally, so on a long guide ``next()`` would
+     *  otherwise advance to a row below the fold. ``block: 'nearest'`` scrolls the
+     *  minimum needed, which also means it does nothing when the row is already
+     *  visible — including in the templates that have no timeline at all. */
+    private _scrollActiveRowIntoView;
+    /** Re-bind the ResizeObserver + animator to a relocated stage element (e.g.
+     *  after a template switch) and reposition the hotspot/tooltip. Does not
+     *  touch step state, so the in-flight play loop continues uninterrupted. */
+    private _reattachStage;
+    next(): void;
+    prev(): void;
+    restart(): void;
+    goTo(index: number): void;
+    private _loadManifest;
+    private _fallbackLayoutKey;
+    private _resolveVariant;
+    private _restartFromStart;
+    private _setupResizeObserver;
+    private _currentStep;
+    /**
+     * The `Capture` the active render reads from — screenshots AND caption.
+     *
+     * Both go through this one accessor on purpose: a step's text can be
+     * overridden per layout (the twin-branch pattern), so reading the frame from
+     * one layout and the wording from another would put "click the row of the
+     * table" above a screenshot of a card list.
+     */
+    private _captureFor;
+    private _contentFor;
+    private _currentFrame;
+    private _currentTargetBbox;
+    private _recomputeHotspot;
+    private _placeTooltip;
+    private _goToStep;
+    /** Resolve the effective cursor mode. Host attribute wins; manifest is the
+     *  fallback; 'arrow' is the final default. Unknown attribute strings fall
+     *  through to the manifest so a typo can't strand the player. */
+    private _effectiveCursorMode;
+    private _playCurrentPosition;
+    private _advance;
+    /** Idempotent: emits ``steppy:hotspot`` with target=correct and resolves the
+     *  current wait. A second call is a no-op (the wait already advanced). */
+    private _confirmHotspotClick;
+    private _onStageClick;
+    private _onHotspotClick;
+    private _handleKeyDown;
+    private _onLocaleChange;
+    private _onVariantChange;
+    private _onImgLoad;
+    private _emit;
+    render(): import("lit-html").TemplateResult;
+    /** The live stage subtree (screenshot + cursor/ripple/kbd + hotspot +
+     *  miss-toast), shared verbatim by every template via the ``renderStage``
+     *  thunk so the refs + handlers stay bound to the component.
+     *
+     *  A template *switch* swaps the whole top-level template, so Lit recreates
+     *  the stage element. That is handled by ``updated`` → ``_reattachStage``
+     *  (re-point the animator + ResizeObserver, recompute placement) WITHOUT
+     *  resetting step state, so the in-flight animation survives the move. The
+     *  floating tooltip is included only in overlay mode (sidebar and inline
+     *  surface the description in their own chrome). */
+    private _renderStage;
+    private _renderHotspot;
+    private _renderTooltip;
+    private _renderMissToast;
+    /** Project the ordered manifest steps into presentation view models. Pure
+     *  projection of engine state — no behavior, no duplicated gates. */
+    private _buildStepViews;
+    /** Display-only duration estimate (~8s/step). Never feeds the play loop. */
+    private _durationLabel;
+    private _buildTemplateContext;
+    /** The built-in template switcher routes through the reflected property so
+     *  ``willUpdate`` re-resolves + persists (and hosts observe the attribute). */
+    private _onTemplateChange;
+    private static readonly TEMPLATE_STORAGE_KEY;
+    private _readPersistedTemplate;
+    private _persistTemplate;
+    /** Resolve the effective template: explicit ``template`` attribute →
+     *  persisted localStorage → manifest ``defaultTemplate`` → 'overlay'.
+     *  Unknown attribute strings fall through so a typo can't strand the player. */
+    private _resolveTemplate;
+    private _renderLoading;
+    private _renderError;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'steppy-guide': SteppyGuide;
+    }
+}
+export { DEFAULT_UI_STRINGS };
+export type { UiStrings };

package/dist/types/templates/base-styles.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared player styles: design tokens, the screenshot stage + cursor/ripple/
+ * kbd/hotspot/tooltip, status/error blocks, and the shared chrome control
+ * primitives (buttons, selects, segmented control) every template composes.
+ *
+ * Design language: warm cream surfaces, near-black text, rust-orange accent,
+ * green for completed steps. Serif titles, sans body, mono meta/counters. All
+ * theming flows through CSS custom properties on ``:host`` so the player stays
+ * overridable; fonts use system stacks only (offline, no CDN).
+ *
+ * The historical engine variable names (``--steppy-hotspot-color`` etc.) are
+ * preserved and merely re-pointed at the new palette so existing host overrides
+ * keep working.
+ */
+export declare const baseStyles: import("lit").CSSResult;

package/dist/types/templates/controls.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared chrome fragments composed by the three templates. Pure functions over
+ * {@link TemplateContext} — no state, no engine logic. Each template arranges
+ * these into its own layout.
+ */
+import { nothing, type TemplateResult } from 'lit';
+import type { TemplateContext } from './types.js';
+export declare function renderProgress(ctx: TemplateContext): TemplateResult;
+/** Compact "i/n" counter (inline + sidebar footers). */
+export declare function renderCounter(ctx: TemplateContext): TemplateResult;
+export declare function renderPrev(ctx: TemplateContext): TemplateResult;
+export declare function renderNext(ctx: TemplateContext): TemplateResult;
+export declare function renderRestart(ctx: TemplateContext): TemplateResult;
+export declare function renderLocaleSelect(ctx: TemplateContext): TemplateResult | typeof nothing;
+export declare function renderLayoutSelect(ctx: TemplateContext): TemplateResult | typeof nothing;
+/** Segmented [Sidebar | Overlay | Inline] control (active = dark fill). */
+export declare function renderTemplateSwitcher(ctx: TemplateContext): TemplateResult;

package/dist/types/templates/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Template registry. The component dispatches ``render()`` to one of these by
+ * the resolved ``template`` id; ``static styles`` aggregates every template's
+ * CSS (unrendered templates simply have no matching DOM).
+ */
+import type { TemplateId, TemplateModule } from './types.js';
+/**
+ * The registry is the single source of truth: registering a template here is
+ * the only edit needed inside this file. `ALL_TEMPLATES`, `isTemplateId` and
+ * `templateStyles` are all derived from it below, so a new template can never
+ * be renderable-but-unstyled or renderable-but-unlistable.
+ */
+export declare const TEMPLATES: Record<TemplateId, TemplateModule>;
+/**
+ * Display/selection order for the segmented switcher — deliberately not the
+ * registry's declaration order, which is why this one list stays explicit.
+ * `templates.test.ts` asserts it covers every registered template.
+ */
+export declare const ALL_TEMPLATES: readonly TemplateId[];
+export declare function isTemplateId(value: unknown): value is TemplateId;
+/** Aggregated styles for the component's ``static styles``. */
+export declare const templateStyles: import("lit").CSSResult[];
+export type { TemplateContext, TemplateId, StepView, TemplateModule } from './types.js';

package/dist/types/templates/inline.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Inline template — full-bleed preview with a slim full-width caption bar: the
+ * step counter, the current localized description, a mono sub-label, and
+ * prev/next. The switchers ride along compactly so the player stays
+ * self-contained, but the bar is the only chrome over the preview.
+ */
+import { type TemplateResult } from 'lit';
+import type { TemplateContext } from './types.js';
+export declare function render(ctx: TemplateContext): TemplateResult;
+export declare const styles: import("lit").CSSResult;

package/dist/types/templates/overlay.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Overlay template — the original/default player presentation: a full-bleed
+ * screenshot stage with a floating callout pinned to the highlighted target,
+ * and a bottom chrome bar. Lifted from the component verbatim (only the new
+ * template switcher is added); engine logic is untouched.
+ */
+import { type TemplateResult } from 'lit';
+import type { TemplateContext } from './types.js';
+export declare function render(ctx: TemplateContext): TemplateResult;
+export declare const styles: import("lit").CSSResult;

package/dist/types/templates/sidebar.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Sidebar template — a fixed left rail (guide title, meta line, vertical step
+ * timeline, current-step description, prev/next + counter) beside the preview.
+ * The current step's full localized description is surfaced in the rail; the
+ * in-stage floating tooltip is suppressed (the stage handles that based on the
+ * active template). Collapses to a single column on narrow containers.
+ *
+ * The rail is height-capped and the timeline scrolls inside it, so a 19-step
+ * guide occupies the same vertical space as a 3-step one. The component pairs
+ * this with ``_scrollActiveRowIntoView`` so advancing never leaves the current
+ * step off-screen. Every layout dimension the cap touches — rail width, rail
+ * height, sticky offset — is a ``--steppy-*`` custom property, because a host
+ * that embeds the player under its own chrome (the Angular target) cannot use
+ * the ``100vh`` default.
+ */
+import { type TemplateResult } from 'lit';
+import type { TemplateContext } from './types.js';
+export declare function render(ctx: TemplateContext): TemplateResult;
+export declare const styles: import("lit").CSSResult;

package/dist/types/templates/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Engine → template contract.
+ *
+ * The engine (the ``<steppy-guide>`` component) owns ALL state and behavior:
+ * manifest, step indices, cursor animation, hotspot/tooltip placement,
+ * navigation, i18n, persistence. A *template* is a pure render function over an
+ * immutable {@link TemplateContext} — it decides only where the chrome lives and
+ * how it looks. Templates never hold step state and never re-implement engine
+ * gates; everything they need (including derived values like step ``status`` and
+ * disabled flags) is precomputed on the context.
+ *
+ * Anything that needs a live DOM ref — the screenshot stage with its
+ * cursor/ripple/kbd/hotspot, and the overlay's floating callout — is supplied as
+ * the {@link TemplateContext.renderStage} thunk, which the component owns so the
+ * ``ref()`` directives and event handlers stay bound to it across template
+ * switches.
+ */
+import type { CSSResult, TemplateResult } from 'lit';
+import type { UiStrings } from '../i18n/ui-strings.js';
+import type { TemplateMode } from '../manifest/schema.js';
+export type TemplateId = TemplateMode;
+/** A single step projected for presentation. Pure projection of engine state —
+ *  no behavior, no duplicated gates. */
+export interface StepView {
+    /** 1-based step index (matches the manifest ``step.index``). */
+    index: number;
+    /** Short heading (sidebar timeline). Falls back to the description. */
+    title: string;
+    /** Full localized instruction body (the manifest ``text``). */
+    description: string;
+    /** Mono meta sub-label (the manifest ``subtitle``). May be empty. */
+    subLabel: string;
+    /** Position relative to the current step. */
+    status: 'completed' | 'current' | 'upcoming';
+    /** True when the step is reachable via ``goTo`` (index ≤ furthest reached). */
+    reachable: boolean;
+}
+export interface TemplateContext {
+    steps: readonly StepView[];
+    /** 1-based index of the current step. */
+    currentIndex: number;
+    total: number;
+    /** Localized, display-only duration estimate (e.g. "~3 min"). */
+    durationLabel: string;
+    /** Localized guide title for the current locale. */
+    guideTitle: string;
+    locale: string;
+    ui: UiStrings;
+    waitingForInput: boolean;
+    completed: boolean;
+    onNext: () => void;
+    onPrev: () => void;
+    onRestart: () => void;
+    /** Jump to a 1-based step index (engine gates to reachable steps). */
+    onGoTo: (index1: number) => void;
+    prevDisabled: boolean;
+    nextDisabled: boolean;
+    locales: readonly string[];
+    layouts: readonly string[];
+    templates: readonly TemplateId[];
+    activeTemplate: TemplateId;
+    activeLocale: string;
+    activeLayout: string | null;
+    hideLayoutSwitcher: boolean;
+    onLocaleChange: (ev: Event) => void;
+    onLayoutChange: (ev: Event) => void;
+    onTemplateChange: (t: TemplateId) => void;
+    /** The ``.steppy-stage`` subtree (img + cursor + ripple + kbd + hotspot +
+     *  miss-toast, and the floating tooltip in overlay mode). Carries the live
+     *  refs + handlers; identical element shape in every template. */
+    renderStage: () => TemplateResult;
+}
+export interface TemplateModule {
+    render(ctx: TemplateContext): TemplateResult;
+    styles: CSSResult;
+}

package/dist/types/tour/api.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The public surface of ``<steppy-tour-host>`` — what an app (or a
+ * framework adapter) programs against.
+ */
+import type { TourSource } from './loader.js';
+import type { TourStringOverrides } from './strings.js';
+export type { TourSource } from './loader.js';
+export type { TourStringOverrides } from './strings.js';
+export interface TourStartOptions {
+    /** Route parameters for the tour's entry (``/invoices/:invoiceId``). */
+    params?: Record<string, string | number>;
+    /** Start at this step id instead of the first. */
+    step?: string;
+}
+export interface TourPosition {
+    tourId: string;
+    stepId: string;
+    /** 0-based among the steps that apply to the current layout. */
+    index: number;
+    total: number;
+}
+export interface TourNavigateContext {
+    /** The same path relative to ``<base href>`` — what a client-side router wants. */
+    appPath: string;
+    tourId: string;
+}
+/**
+ * Navigate the app to a tour's entry (or a route linked from step text).
+ * ``path`` is the document path, base included. Default: ``location.assign``.
+ * A returned promise is awaited (its value is ignored); a rejection fails the
+ * start with ``entry-params``. Router calls fit as they are:
+ * ``(_, { appPath }) => router.navigateByUrl(appPath)``.
+ */
+export type TourNavigate = (path: string, ctx: TourNavigateContext) => void | PromiseLike<unknown>;
+export interface TourHostApi {
+    manifest: string;
+    fallbackManifest: string;
+    buildId: string;
+    locale: string;
+    guideOrigin: string;
+    baseZIndex: number;
+    targetTimeout: number;
+    disabled: boolean;
+    source: TourSource | null;
+    navigate: TourNavigate | null;
+    strings: TourStringOverrides | undefined;
+    /** Start a tour. Resolves true once it started; never rejects. */
+    start(tourId: string, options?: TourStartOptions): Promise<boolean>;
+    stop(reason?: string): void;
+    /** Advance the current step, whatever its kind. */
+    next(): void;
+    readonly isActive: boolean;
+    readonly current: TourPosition | null;
+}

package/dist/types/tour/contract.d.ts

@@ -0,0 +1,54 @@
+/**
+ * In-app tour data contract v1, the TypeScript twin of ``src/steppy/tour_spec.py``.
+ *
+ * The overlay validates every manifest and tour file against these values
+ * (``validate.ts``); the compiler never emits anything they reject.
+ * ``tests/test_tour_contract_sync.py`` keeps both sides equal, so every value
+ * stays a plain literal: string patterns carry no backslashes, and arrays are
+ * written on one line.
+ */
+export declare const TOUR_SCHEMA_VERSION = 1;
+export declare const ADVANCE_KINDS: readonly ["click", "input", "change", "visible", "manual"];
+export declare const TARGETED_ADVANCE_KINDS: readonly ["click", "input", "change", "visible"];
+export declare const PLACEMENTS: readonly ["top", "bottom", "left", "right", "auto"];
+export declare const TOUR_EVENTS: readonly ["tour-start", "tour-step", "tour-complete", "tour-dismiss", "tour-offpath", "tour-error"];
+export declare const TOUR_ERROR_REASONS: readonly ["target-timeout", "entry-params", "load-failed", "schema-unsupported", "invalid-data"];
+export declare const TOUR_PARTS: readonly ["layer", "spotlight", "bubble", "title", "body", "progress", "button", "primary", "secondary", "next", "close", "skip", "end", "resume", "pill", "guide-link"];
+export declare const ATTR_TOUR_ID = "data-tour-id";
+export declare const ATTR_STEP_ID = "data-step-id";
+export declare const ATTR_STATE = "data-state";
+export declare const ATTR_ADVANCE = "data-advance";
+export declare const BUBBLE_STATES: readonly ["shown", "fallback"];
+/** Languages ``strings.ts`` ships chrome strings for; others need the host's ``strings``. */
+export declare const CHROME_STRING_LOCALES: readonly ["en", "fr", "nl", "de"];
+export declare const TEST_ID_PATTERN = "^[A-Za-z0-9_.:/-]{1,128}$";
+export declare const STEP_ID_PATTERN = "^[A-Za-z0-9_.:/-]{1,128}$";
+export declare const TEST_ID_ATTRIBUTE_PATTERN = "^data-[a-z0-9-]+$";
+export declare const TOUR_ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$";
+export declare const LAYOUT_NAME_PATTERN = "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$";
+export declare const ROLE_PATTERN = "^[A-Za-z0-9_-]{1,64}$";
+export declare const LOCALE_PATTERN = "^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{1,8}){0,5}$";
+export declare const SRI_PATTERN = "^sha384-[A-Za-z0-9+/]{64}$";
+export declare const TOUR_FILE_NAME_PATTERN = "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}[.][A-Za-z0-9_-]{1,64}[.]json$";
+export declare const ROUTE_PATTERN = "^/$|^(?:/(?::[A-Za-z_][A-Za-z0-9_]{0,63}|[A-Za-z0-9._~%!$&()*+,;=@-]{1,128})){1,32}$";
+export declare const MEDIA_QUERY_PATTERN = "^[A-Za-z0-9 :().,<>=/_-]{1,256}$";
+export declare const BUILD_ID_PATTERN = "^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62}[A-Za-z0-9])?$";
+export declare const MAX_TOURS = 500;
+export declare const MAX_STEPS = 100;
+export declare const MAX_LOCALES = 32;
+export declare const MAX_LAYOUTS = 16;
+export declare const MAX_TITLE_CHARS = 200;
+export declare const MAX_TEXT_CHARS = 2000;
+export declare const MAX_ROUTE_CHARS = 512;
+export declare const MAX_URL_CHARS = 2048;
+export declare const MAX_MEDIA_QUERY_CHARS = 256;
+export declare const MAX_TOUR_FILE_BYTES = 262144;
+export declare const MAX_MANIFEST_BYTES = 1048576;
+/** Player-only defaults (no Python twin). */
+export declare const DEFAULT_TARGET_TIMEOUT_MS = 8000;
+export declare const DEFAULT_BASE_Z_INDEX = 2147483000;
+export type AdvanceKind = (typeof ADVANCE_KINDS)[number];
+export type Placement = (typeof PLACEMENTS)[number];
+export type TourEventName = (typeof TOUR_EVENTS)[number];
+export type TourErrorReason = (typeof TOUR_ERROR_REASONS)[number];
+export type TourPart = (typeof TOUR_PARTS)[number];

package/dist/types/tour/dom.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Everything the overlay asks the browser about geometry and timing, behind
+ * one interface. ``defaultDom`` is the real thing; tests swap
+ * ``SteppyTourHost.dom`` for a stub with settable rects and a manual
+ * scheduler (happy-dom has no layout, and its rAF escapes fake timers).
+ */
+import { type Rect } from '../ui/placement.js';
+export interface Scheduler {
+    now(): number;
+    raf(cb: () => void): number;
+    cancelRaf(id: number): void;
+    setTimeout(cb: () => void, ms: number): number;
+    clearTimeout(id: number): void;
+    setInterval(cb: () => void, ms: number): number;
+    clearInterval(id: number): void;
+}
+export interface Viewport {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface DomAdapter {
+    scheduler: Scheduler;
+    /** The element's effective rect (see ``effectiveRect``), or null when it has none. */
+    rect(el: Element): Rect | null;
+    isVisible(el: Element): boolean;
+    /** The visual viewport, in layout-viewport coordinates. */
+    viewport(): Viewport;
+    matchMedia(query: string): boolean;
+    reducedMotion(): boolean;
+    scrollIntoView(el: Element, instant: boolean): void;
+    supportsPopover(): boolean;
+}
+/**
+ * Playwright's notion of a visible box, extended for wrapper hosts: an element
+ * with ``display: contents`` measures as the union of its children, and an
+ * empty 0x0 host (a custom element wrapping a native control) as its first
+ * visible focusable descendant.
+ */
+export declare function effectiveRect(el: Element, depth?: number): Rect | null;
+export declare const defaultScheduler: Scheduler;
+export declare const defaultDom: DomAdapter;