@glowhop/core-tour 1.0.0

package/config/types.d.ts

@@ -0,0 +1,136 @@
+import type { WorkflowDefinition } from "../definition";
+import type { IndicatorOptions, LifecycleHookContext, OverlayOptions, PopoverOptions, PrimitiveValue, StepAction, StepBehavior, StepTransitionAction } from "../types";
+/**
+ * A tour-level lifecycle hook callback (`onStart`, `onCancel`, `onFinish`), generic over the
+ * config's content type `T` (defaults to `string`, the untrusted-JSON case).
+ *
+ * There is no built-in (JSON-object) form for this slot: `LifecycleHookContext` carries no
+ * `target` at all (only `step: TourCurrentStep<T> | null`), so none of the DOM-oriented
+ * `BuiltinAction` variants (which all assume a `target`/`signal`) have a valid mapping here. A
+ * lifecycle hook is therefore only expressible as a same-runtime JS function — never as plain
+ * JSON.
+ */
+export type LifecycleActionRef<T = string> = (context: LifecycleHookContext<T>) => void | Promise<void>;
+/**
+ * One of the built-in action instructions, discriminated by `type`. Each variant maps 1:1 onto an
+ * existing `WorkflowStepBuilder` verb and mirrors its options.
+ *
+ * There is no `waitUntil` variant: a `waitUntil` predicate is arbitrary logic and cannot be
+ * expressed as JSON, and this format has no registry to reference one by id.
+ * `{ type: "waitUntilElement" }` covers the common case of waiting for a condition — waiting for
+ * an element to appear — without needing an arbitrary predicate.
+ *
+ * Not generic: a builtin action holds no content, so it carries no `T`.
+ */
+export type BuiltinAction = {
+    readonly type: "wait";
+    readonly ms: number;
+} | {
+    readonly type: "waitUntilElement";
+    readonly selector: string;
+    readonly interval?: number;
+    readonly timeout?: number;
+} | {
+    readonly type: "clickTarget";
+} | {
+    readonly type: "focusTarget";
+};
+/**
+ * A reference to a step action, resolved at build time by discriminating on its runtime shape:
+ * - `typeof ref === "function"` -> used inline as-is (JS escape hatch, not serializable).
+ * - a plain object with a `type` field -> a {@link BuiltinAction}, mapped onto the matching
+ *   builder verb.
+ * - anything else is a validation error.
+ *
+ * Used for `actions[]` and `eventHandlers[].action`, which both run against a full `StepContext`
+ * (`target`, `signal`, navigation methods) — the same context `BuiltinAction`'s verbs assume, so
+ * builtins are valid here.
+ */
+export type StepActionRef<T = string> = BuiltinAction | StepAction<T>;
+/**
+ * A reference to a transition hook (`advanceAction`/`previousAction`/`cancelAction`).
+ *
+ * `BeforeActionStepContext` has a `target` but no `signal`/navigation methods, which the
+ * `BuiltinAction` verbs (`wait`, `waitUntilElement`, `clickTarget`, `focusTarget`) all need — none
+ * of them can run in this slot. With no registry to fall back on, a transition hook is therefore
+ * only expressible as a same-runtime JS function, never as plain JSON. This is a plain function
+ * type (not a union) precisely because there is nothing else valid to put here.
+ */
+export type TransitionActionRef<T = string> = StepTransitionAction<T>;
+/** JSON config form of a single `onTargetEvent` registration. */
+export interface EventHandlerConfig<T = string> {
+    /** Event name, or multiple event names sharing the same action. */
+    readonly event: string | readonly string[];
+    readonly action: StepActionRef<T>;
+}
+/**
+ * JSON config form of a single tour step.
+ *
+ * Generic over `T`, the type of `title`/`content`. Defaults to `string` for the untrusted-JSON
+ * path (`JSON.parse()` output); callers building same-runtime configs can instantiate with their
+ * framework's content type (e.g. `StepConfig<ReactNode>`) to pass rich content straight through.
+ */
+export interface StepConfig<T = string> {
+    /** Stable identifier for this step, unique within the workflow. Required. */
+    readonly id: string;
+    /** CSS selector for the step's target. Functions and `HTMLElement` are not supported in config form. */
+    readonly target: string;
+    readonly resetPropsOnEnter?: boolean;
+    readonly overlay?: OverlayOptions;
+    readonly popover?: PopoverOptions;
+    readonly indicator?: IndicatorOptions;
+    readonly behavior?: StepBehavior;
+    readonly title: T;
+    readonly content: T;
+    readonly data?: Record<string, PrimitiveValue>;
+    readonly actions?: readonly StepActionRef<T>[];
+    readonly eventHandlers?: readonly EventHandlerConfig<T>[];
+    readonly advanceAction?: TransitionActionRef<T>;
+    readonly previousAction?: TransitionActionRef<T>;
+    readonly cancelAction?: TransitionActionRef<T>;
+}
+/**
+ * A complete, JSON-serializable tour definition.
+ *
+ * Generic over `T` (defaults to `string`) so the same format covers both the untrusted-JSON path
+ * and same-runtime configs carrying framework content (`ReactNode`, `VNode`, `JSX.Element`, ...).
+ */
+export interface WorkflowConfig<T = string> {
+    readonly name: string;
+    readonly cancellable?: boolean;
+    readonly allowScroll?: boolean;
+    readonly overlay?: OverlayOptions;
+    readonly popover?: PopoverOptions;
+    readonly indicator?: IndicatorOptions;
+    readonly animated?: boolean;
+    readonly behavior?: StepBehavior;
+    readonly onStart?: LifecycleActionRef<T>;
+    readonly onCancel?: LifecycleActionRef<T>;
+    readonly onFinish?: LifecycleActionRef<T>;
+    readonly steps: readonly StepConfig<T>[];
+}
+/** A single validation failure, with a path pointing at the offending config field. */
+export interface ConfigValidationIssue {
+    /** Path into the config, e.g. `steps[2].eventHandlers[0].action`. */
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * Aggregate error thrown when a `WorkflowConfig` fails validation.
+ *
+ * Carries every issue found in a single pass over the whole config (decision: fail-fast on the
+ * first problem would force multiple edit/re-run cycles for a hand-written or generated JSON
+ * document), rather than throwing on the first issue encountered.
+ */
+export declare class ConfigValidationError extends Error {
+    readonly issues: readonly ConfigValidationIssue[];
+    constructor(issues: readonly ConfigValidationIssue[]);
+}
+/**
+ * The `WorkflowDefinition` produced from a `WorkflowConfig<T>`, with the original (frozen) config
+ * attached so a future JSON exporter can round-trip cheaply without re-deriving it from the built
+ * definition.
+ */
+export interface WorkflowDefinitionFromConfig<T = string> extends WorkflowDefinition<T> {
+    readonly source: Readonly<WorkflowConfig<T>>;
+}

package/config/validate.d.ts

@@ -0,0 +1,37 @@
+import type { WorkflowConfig } from "./types";
+/**
+ * Validates a `title`/`content` value at `path`. Returns an error message, or `null` when the
+ * value is acceptable.
+ * @param value The candidate value.
+ * @param path Error path for this field, e.g. `steps[2].title`.
+ * @param validateContent Custom content validator; when omitted, the value must be a `string`.
+ */
+type ContentValidator = (value: unknown, path: string) => string | null;
+/** Options accepted by `validateWorkflowConfig` (and threaded through internally). */
+export interface ValidateWorkflowConfigOptions {
+    /**
+     * Validates `title`/`content` values. Returns an error message, or `null` when the value is
+     * acceptable. Omit this to keep the default strict behavior — `title`/`content` must be plain
+     * strings — which is required for the untrusted-JSON path (`JSON.parse()` output). Callers using
+     * a rich content type `T` (e.g. `ReactNode`) must supply this to accept non-string values.
+     */
+    readonly validateContent?: ContentValidator;
+}
+/**
+ * Validates and narrows an unknown value to a `WorkflowConfig<T>`.
+ *
+ * Performs a single pass over the whole config, collecting every issue (unknown/extra keys, wrong
+ * types, missing required fields, invalid nested options, builtins used in slots that cannot run
+ * them, etc.) rather than throwing on the first one — see `ConfigValidationError`.
+ *
+ * By default, `title`/`content` must be plain strings — the runtime cannot otherwise know what
+ * `T` is, and this default keeps the untrusted-JSON path strict. Pass `options.validateContent`
+ * to accept a richer `T` (e.g. `ReactNode`).
+ *
+ * @param config The parsed JSON (or equivalent plain object) to validate.
+ * @param options Validation options; see {@link ValidateWorkflowConfigOptions}.
+ * @throws {ConfigValidationError} When one or more issues are found.
+ * @returns The same value, narrowed to `WorkflowConfig<T>`.
+ */
+export declare function validateWorkflowConfig<T = string>(config: unknown, options?: ValidateWorkflowConfigOptions): WorkflowConfig<T>;
+export {};

package/core.browser.d.ts

@@ -0,0 +1 @@
+export {};

package/definition/index.d.ts

@@ -0,0 +1,3 @@
+export { cloneStepProps, freezeStepProps } from "./step-props";
+export type { DeepReadonly, ReadonlyStartOptions, ReadonlyStepProps, StepProps, WorkflowDefinition, WorkflowStepDefinition, } from "./types";
+export { cloneWorkflowStepDraft, createWorkflowDefinition, type WorkflowStepDraft, } from "./workflow-definition";

package/definition/step-props.d.ts

@@ -0,0 +1,13 @@
+import type { ReadonlyStepProps, StepProps } from "./types";
+/**
+ * Creates a shallow clone of step properties with deep clones of nested objects.
+ * @param props The properties to clone.
+ * @returns A mutable copy of the properties.
+ */
+export declare function cloneStepProps<T>(props: ReadonlyStepProps<T>): StepProps<T>;
+/**
+ * Creates a deep-frozen copy of step properties.
+ * @param props The properties to freeze.
+ * @returns An immutable copy of the properties.
+ */
+export declare function freezeStepProps<T>(props: ReadonlyStepProps<T>): ReadonlyStepProps<T>;

package/definition/types.d.ts

@@ -0,0 +1,38 @@
+import type { EventHandler, IndicatorOptions, OverlayOptions, PopoverOptions, PrimitiveValue, StartOptions, StepActionInstruction, StepBehavior, StepParameters, StepTransitionAction, TargetResolver } from "../types";
+/** Recursively makes all properties readonly at any depth. */
+export type DeepReadonly<T> = T extends (...arguments_: infer _Arguments) => infer _Return ? T : T extends readonly (infer TEntry)[] ? readonly DeepReadonly<TEntry>[] : T extends object ? {
+    readonly [TKey in keyof T]: DeepReadonly<T[TKey]>;
+} : T;
+/** Step properties (title, content, and optional display options) excluding target and behavior. */
+export type StepProps<T> = Omit<StepParameters<T>, "id" | "target" | "resetPropsOnEnter" | "behavior">;
+/** Immutable step properties. */
+export type ReadonlyStepProps<T> = {
+    readonly title: T;
+    readonly content: T;
+    readonly data?: Readonly<Record<string, PrimitiveValue>>;
+    readonly overlay?: DeepReadonly<OverlayOptions>;
+    readonly popover?: DeepReadonly<PopoverOptions>;
+    readonly indicator?: DeepReadonly<IndicatorOptions>;
+};
+/** Immutable tour start options. */
+export type ReadonlyStartOptions<T> = DeepReadonly<StartOptions<T>>;
+/** A single step in a tour workflow (immutable). */
+export interface WorkflowStepDefinition<T> {
+    /** Stable identifier, unique within the workflow. */
+    readonly id: string;
+    readonly target: TargetResolver;
+    readonly resetPropsOnEnter?: boolean;
+    readonly behavior?: DeepReadonly<StepBehavior>;
+    readonly props: ReadonlyStepProps<T>;
+    readonly actions: readonly StepActionInstruction<T>[];
+    readonly eventHandlers: readonly EventHandler<T>[];
+    readonly advanceAction: StepTransitionAction<T> | null;
+    readonly previousAction: StepTransitionAction<T> | null;
+    readonly cancelAction: StepTransitionAction<T> | null;
+}
+/** A complete tour workflow definition (immutable). */
+export interface WorkflowDefinition<T> {
+    readonly name: string;
+    readonly options: ReadonlyStartOptions<T>;
+    readonly steps: readonly WorkflowStepDefinition<T>[];
+}

package/definition/workflow-definition.d.ts

@@ -0,0 +1,28 @@
+import type { EventHandler, StartOptions, StepActionInstruction, StepParameters, StepTransitionAction } from "../types";
+import type { StepProps, WorkflowDefinition, WorkflowStepDefinition } from "./types";
+export interface WorkflowStepDraft<T> {
+    id: string;
+    target: StepParameters<T>["target"];
+    resetPropsOnEnter?: boolean;
+    props: StepProps<T>;
+    behavior?: StepParameters<T>["behavior"];
+    actions: StepActionInstruction<T>[];
+    eventHandlers: EventHandler<T>[];
+    advanceAction: StepTransitionAction<T> | null;
+    previousAction: StepTransitionAction<T> | null;
+    cancelAction: StepTransitionAction<T> | null;
+}
+/**
+ * Creates a mutable copy of a workflow step definition.
+ * @param definition The step definition to clone.
+ * @returns A mutable copy that can be further modified.
+ */
+export declare function cloneWorkflowStepDraft<T>(definition: WorkflowStepDefinition<T> | WorkflowStepDraft<T>): WorkflowStepDraft<T>;
+/**
+ * Creates a frozen workflow definition from a name, options, and step drafts.
+ * @param name The workflow name.
+ * @param options Tour start options and lifecycle hooks.
+ * @param drafts The workflow steps.
+ * @returns A frozen workflow definition ready to run.
+ */
+export declare function createWorkflowDefinition<T>(name: string, options: StartOptions<T>, drafts: readonly WorkflowStepDraft<T>[]): WorkflowDefinition<T>;

package/dom/dom-mutation-lease.d.ts

@@ -0,0 +1,13 @@
+export declare class DomMutationLease {
+    private readonly element;
+    private readonly attributes;
+    private readonly styles;
+    private released;
+    constructor(element: HTMLElement | SVGElement);
+    setAttribute(name: string, value: string | null): void;
+    setStyle(name: string, value: string | null, priority?: string): void;
+    releaseStyle(name: string): void;
+    release(): void;
+    private styleMutation;
+    private restoreStyle;
+}

package/dom/tour-view-driver.d.ts

@@ -0,0 +1,113 @@
+import type { ActiveStep } from "../runtime/active-step";
+import type { TourDirection, TourEventSource } from "../types";
+export interface TourViewCommands {
+    advance(source: TourEventSource): Promise<void>;
+    canAdvance(): boolean;
+    canCancel(): boolean;
+    canPrevious(): boolean;
+    isAdvanceDisabled(): boolean;
+    isCancelDisabled(): boolean;
+    isPreviousDisabled(): boolean;
+    previous(source: TourEventSource): Promise<void>;
+    cancel(source: TourEventSource): Promise<void>;
+    reportError(error: unknown): Promise<void>;
+    targetDisconnected(target: HTMLElement): Promise<void>;
+    subscribeCapabilities?(listener: (active: boolean) => void): () => void;
+}
+export interface TourViewDriver<T> {
+    show(step: ActiveStep<T>, direction: TourDirection, signal: AbortSignal, onBeforePopoverAppear?: () => void | Promise<void>): Promise<void> | void;
+    clear(signal: AbortSignal): Promise<void> | void;
+    dispose(): void;
+    releaseMount?(): void;
+    setCommands?(commands: TourViewCommands): void;
+}
+export declare class NoopTourViewDriver<T> implements TourViewDriver<T> {
+    show(_step: ActiveStep<T>, _direction: TourDirection, _signal: AbortSignal, onBeforePopoverAppear?: () => void | Promise<void>): void | Promise<void> | undefined;
+    clear(_signal: AbortSignal): void;
+    dispose(): void;
+    releaseMount(): void;
+}
+export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
+    private readonly focusGuard;
+    private readonly scrollLock;
+    private readonly modalToken;
+    private readonly stepCleanups;
+    private commands;
+    private direction;
+    private currentStep;
+    private currentSignal;
+    private disposed;
+    private generation;
+    private active;
+    private lastTargetRect;
+    private lastViewport;
+    private inertBranches;
+    private modalDocument;
+    private modalRoot;
+    private overlay;
+    private pendingKeyboardCommand;
+    private pointer;
+    private pendingFocusGeneration;
+    private popover;
+    private presentationDirty;
+    private rafId;
+    private rafCancel;
+    private root;
+    private scrollAbort;
+    constructor(commands?: TourViewCommands);
+    setCommands(commands: TourViewCommands): void;
+    registerRoot(element: HTMLElement | null): void;
+    registerOverlay(element: SVGSVGElement | null): void;
+    registerPopover(element: HTMLElement | null): void;
+    registerPointer(element: HTMLElement | null): void;
+    show(step: ActiveStep<T>, direction: TourDirection, signal: AbortSignal, onBeforePopoverAppear?: () => void | Promise<void>): Promise<void>;
+    clear(signal: AbortSignal): Promise<void>;
+    releaseMount(): void;
+    dispose(): void;
+    private refreshRegisteredElements;
+    private activateRegisteredElements;
+    private initializeElements;
+    private syncModality;
+    private releaseModality;
+    private restoreInertBranches;
+    private appear;
+    private attachStepResources;
+    private listen;
+    private schedulePosition;
+    private updatePosition;
+    private observeDynamicOperation;
+    private handleKeydown;
+    private handleOverlayClick;
+    private queueTransitionKeydown;
+    private flushPendingKeyboardCommand;
+    private loopFocus;
+    private activateFocus;
+    private syncScrollLock;
+    private syncShortcutLabels;
+    private attachButtonHandlers;
+    private findClickedTrigger;
+    private observeControls;
+    private deferTriggerCommand;
+    private syncControlState;
+    private findTriggers;
+    private ownsTrigger;
+    private command;
+    private commandForGeneration;
+    private commandForStep;
+    private canCommand;
+    private syncControl;
+    private isConsumerDisabled;
+    private isLiveDisabled;
+    private isPointerEnabled;
+    private cleanupStepResources;
+    private isCurrentTargetAvailable;
+    private stopForDisconnectedTarget;
+    private beginGeneration;
+    private cancelAnimationsOnAbort;
+    private cancelElementAnimations;
+    private isCurrentGeneration;
+    private scrollTargetIntoView;
+    private throwIfAborted;
+    private throwIfStale;
+    private getWindow;
+}

package/elements/base.d.ts

@@ -0,0 +1,62 @@
+import type { IndicatorOptions, OverlayOptions, PopoverOptions } from "../types";
+export interface TourElementStep {
+    readonly indicator?: IndicatorOptions;
+    readonly overlay?: OverlayOptions;
+    readonly popover?: PopoverOptions;
+}
+export default abstract class GlowTourElement {
+    protected element: HTMLElement | SVGSVGElement;
+    options?: {
+        duration?: number;
+        easing?: string;
+        disabled?: boolean;
+    } | undefined;
+    private readonly animations;
+    private readonly cancelledAnimations;
+    private released;
+    constructor(element: HTMLElement | SVGSVGElement, options?: {
+        duration?: number;
+        easing?: string;
+        disabled?: boolean;
+    } | undefined);
+    setAnimationOptions(options: {
+        duration?: number;
+        easing?: string;
+        disabled?: boolean;
+    }): void;
+    protected _getAnimationOptions(): KeyframeAnimationOptions;
+    protected _isAnimated(): boolean;
+    protected _startAnimation(keyframes: Keyframe[] | PropertyIndexedKeyframes, options?: KeyframeAnimationOptions, target?: Element): Animation | null;
+    /**
+     * The document driving `animation.finished`, when there is one.
+     *
+     * `Animation.timeline` is the document timeline, and a hidden document
+     * freezes it — see {@link _finishWhileDocumentHidden}.
+     */
+    private _getDocument;
+    /**
+     * Ends an animation that cannot progress, and keeps ending it for as long as
+     * the document stays hidden.
+     *
+     * A hidden document freezes its timeline: `currentTime` stops advancing, the
+     * animation stays `running` forever, and `animation.finished` never settles.
+     * Awaiting it would strand the caller — a tour transition would never
+     * complete, leaving the controller stuck in `transitioning`. Finishing the
+     * animation resolves `finished` even on a frozen timeline, so the transition
+     * lands on its final state immediately instead of hanging.
+     *
+     * @returns A cleanup function removing the visibility listener.
+     */
+    private _finishWhileDocumentHidden;
+    protected _waitForAnimation(animation: Animation): Promise<boolean>;
+    protected abstract _disappear(): Promise<void>;
+    protected abstract _getNextStyles(position: DOMRect, step: TourElementStep): Keyframe;
+    abstract updatePosition(nextPosition: DOMRect, step: TourElementStep): void;
+    abstract initializeProps(): void;
+    getElement(): HTMLElement | SVGSVGElement | null;
+    disappear(): Promise<void>;
+    release(): void;
+    cancelAnimations(): void;
+    protected _cancelAnimation(animation: Animation): void;
+    protected abstract _release(): void;
+}

package/elements/idle-presentation.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Single source of truth for the "idle" presentation of tour elements — the
+ * out-of-flow, invisible layout each element must have before a tour ever
+ * runs (or before an adapter's runtime has bound to the DOM at all).
+ *
+ * `initializeProps()` on {@link OverlayElement}, {@link PointerElement} and
+ * {@link PopoverElement} applies these same constants imperatively once an
+ * adapter binds an element. Framework adapters render them directly into
+ * their markup (server and client alike) so the idle state holds even
+ * before hydration/binding runs, with no dependency on `@glowhop/styles-tour`
+ * or any other optional theme.
+ *
+ * Deliberately excluded: the overlay's `viewBox`, which depends on the live
+ * viewport and can only be computed once the element exists in a real DOM.
+ */
+/** A CSS declaration block keyed by kebab-case property names. */
+export type CssStyleRecord = Readonly<Record<string, string>>;
+/** Idle inline style for the overlay `<svg>` element. */
+export declare const OVERLAY_IDLE_STYLE: CssStyleRecord;
+/** Idle attributes for the overlay `<svg>` element. */
+export declare const OVERLAY_IDLE_ATTRIBUTES: {
+    readonly "aria-hidden": "true";
+    readonly "data-glow-tour-allow-interaction": "false";
+    readonly inert: "true";
+};
+/**
+ * Idle attributes for the overlay's cutout `<path>`. Genuinely load-bearing,
+ * not dead code: the parent `<svg>` is `pointer-events: none` and
+ * `setInteractionAllowed` toggles it, so `pointer-events: auto` here is what
+ * makes only the drawn region clickable — what `behavior.overlayClick`
+ * depends on.
+ */
+export declare const OVERLAY_PATH_IDLE_ATTRIBUTES: {
+    readonly cursor: "auto";
+    readonly opacity: "0";
+    readonly "pointer-events": "auto";
+};
+/** Idle inline style for the pointer/indicator element. */
+export declare const POINTER_IDLE_STYLE: CssStyleRecord;
+/** Idle attributes for the pointer/indicator element. */
+export declare const POINTER_IDLE_ATTRIBUTES: {
+    readonly "aria-hidden": "true";
+};
+/** Idle inline style for the popover element. */
+export declare const POPOVER_IDLE_STYLE: CssStyleRecord;
+/** Idle attributes for the popover element. */
+export declare const POPOVER_IDLE_ATTRIBUTES: {
+    readonly "aria-hidden": "true";
+    readonly inert: "true";
+    readonly tabindex: "-1";
+};
+/**
+ * Serializes a style record to CSS text, e.g. for a static `style="..."`
+ * attribute (Vanilla, Angular).
+ */
+export declare function styleRecordToCssText(style: CssStyleRecord): string;
+/**
+ * Converts a kebab-case style record to a camelCase object, as required by
+ * React's `style` prop. Vue and Solid accept kebab-case property names
+ * directly and can use the canonical record as-is.
+ */
+export declare function styleRecordToCamelCase(style: CssStyleRecord): Readonly<Record<string, string>>;

package/elements/overlay.d.ts

@@ -0,0 +1,22 @@
+import GlowTourElement, { type TourElementStep } from "./base";
+export default class OverlayElement extends GlowTourElement {
+    private currentTransition;
+    private visualState;
+    setInteractionAllowed(allowed: boolean): void;
+    moveToTarget(nextPosition: DOMRect, step: TourElementStep): Promise<void>;
+    animateTo(position: DOMRect, step: TourElementStep): Promise<void>;
+    _getNextStyles(position: DOMRect, step: TourElementStep): Keyframe;
+    initializeProps(): void;
+    private _getPathElement;
+    protected _release(): void;
+    updatePosition(nextPosition: DOMRect, step: TourElementStep, animateChanges?: boolean, onTransition?: (transition: Promise<void>) => void): void;
+    cancelAnimations(): void;
+    private applyStyles;
+    private commitAndCancelCurrentTransition;
+    private getCurrentRenderedStyles;
+    private getRenderedTargetStyles;
+    private _getVisualState;
+    private _isSameVisualState;
+    _appear(position: DOMRect, step: TourElementStep): Promise<void>;
+    _disappear(): Promise<void>;
+}

package/elements/pointer.d.ts

@@ -0,0 +1,24 @@
+import type { ResolvedPlacement } from "../types";
+import GlowTourElement, { type TourElementStep } from "./base";
+export default class PointerElement extends GlowTourElement {
+    private animation;
+    private popoverPlacement?;
+    private directionNodes;
+    initializeProps(): void;
+    protected _getNextStyles(position: DOMRect, step: TourElementStep): Keyframe;
+    moveToTarget(nextPosition: DOMRect, step: TourElementStep, appear: boolean, popoverPlacement?: ResolvedPlacement): Promise<void>;
+    updatePosition(nextPosition: DOMRect, step: TourElementStep, popoverPlacement?: ResolvedPlacement): void;
+    syncVisibility(visible: boolean, position: DOMRect, step: TourElementStep, popoverPlacement?: ResolvedPlacement): void;
+    cancelAnimations(): void;
+    private _appear;
+    protected _disappear(): Promise<void>;
+    private _resolvePosition;
+    private _getCandidates;
+    private _startPointerAnimation;
+    private _stopAnimation;
+    protected _release(): void;
+    private _setPlacement;
+    private _syncDirectionVisibility;
+    private _ensureDirectionNodes;
+    private _getTargetTransform;
+}

package/elements/popover-arrow-styles.d.ts

@@ -0,0 +1,5 @@
+export interface PopoverArrowStylesOptions {
+    readonly nonce?: string;
+    readonly disabled?: boolean;
+}
+export declare function ensurePopoverArrowStyles(element: Element, options?: PopoverArrowStylesOptions): void;

package/elements/popover.d.ts

@@ -0,0 +1,33 @@
+import type { ResolvedPlacement } from "../types";
+import GlowTourElement, { type TourElementStep } from "./base";
+export interface PopoverPosition {
+    placement: ResolvedPlacement;
+    x: number;
+    y: number;
+    arrowOffset: number | null;
+}
+export default class PopoverElement extends GlowTourElement {
+    private appliedPosition;
+    private pendingReposition;
+    private repositionPhase;
+    private repositionGeneration;
+    private readonly mutationLease;
+    protected _getNextStyles(position: DOMRect, step: TourElementStep): Keyframe;
+    resolvePosition(targetPosition: DOMRect, step: TourElementStep): PopoverPosition;
+    private _centerPosition;
+    private _applyPositionState;
+    moveToTarget(nextPosition: DOMRect, step: TourElementStep, appear: boolean, onChange?: () => void | Promise<void>): Promise<void>;
+    initializeProps(): void;
+    updatePosition(nextPosition: DOMRect, step: TourElementStep, onReposition?: (reposition: Promise<void>) => void): ResolvedPlacement;
+    cancelAnimations(): void;
+    private _flushReposition;
+    private _applyTransform;
+    private _stationaryPosition;
+    private _applyArrowStyles;
+    private _applyArrowStyle;
+    _appear(position: DOMRect, step: TourElementStep): Promise<void>;
+    _disappear(): Promise<void>;
+    protected _release(): void;
+    private _applyVisibleState;
+    private _applyHiddenState;
+}

package/index.d.ts

@@ -0,0 +1,4 @@
+export type { EventName, WorkflowBuilder, WorkflowStepBuilder } from "./builder";
+export type { ReadonlyStartOptions, ReadonlyStepProps, WorkflowDefinition, WorkflowStepDefinition, } from "./definition";
+export { createGlowTour } from "./runtime/tour-controller";
+export type { AnimationOptions, BaseOptions, BeforeActionStepContext, EventHandler, GlowTour, GlowTourOptions, IndicatorOptions, LifecycleHookContext, OverlayOptions, PopoverArrowOptions, PopoverOptions, PrimitiveValue, ReadonlyTourState, ResolvedPlacement, ScrollOptions, StartOptions, StepAction, StepActionInstruction, StepActionResult, StepBehavior, StepContext, StepEventContext, StepParameters, StepPropsStore, StepPropsUpdate, StepTransitionAction, TargetResolver, TargetResolverContext, TourCurrentStep, TourDirection, TourEvent, TourEventListener, TourEventSource, TourEventType, TourState, TourStatus, TryOrderOptions, WaitUntilOptions, } from "./types";