demoghost 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,745 @@
+export declare class AccessibilityManager {
+    private liveRegion;
+    private previousActiveElement;
+    private keydownHandler;
+    private announcementTimer;
+    constructor();
+    private initLiveRegion;
+    saveFocus(): void;
+    restoreFocus(): void;
+    announce(message: string): void;
+    bindKeyboardControls(options: {
+        onStop: () => void;
+        onTogglePause: () => void;
+    }): void;
+    destroy(): void;
+}
+
+export declare interface ActionExecutionContext {
+    step: DemoStep;
+    stepIndex: number;
+    totalSteps: number;
+    targetResolver: TargetResolverInterface;
+    cursor: CursorEngineInterface;
+    scrollEngine: ScrollEngineInterface;
+    spotlightEngine: SpotlightEngineInterface;
+    options: PlaybackOptions;
+    signal: AbortSignal;
+    isPaused: () => boolean;
+    waitIfPaused: () => Promise<void>;
+    log: (msg: string, ...args: any[]) => void;
+}
+
+export declare interface ActionHandler {
+    execute(context: ActionExecutionContext): Promise<void>;
+}
+
+export declare class ActionRegistry {
+    private handlers;
+    register(type: ActionType, handler: ActionHandler | ((context: ActionExecutionContext) => Promise<void>)): void;
+    get(type: ActionType): ActionHandler;
+    has(type: ActionType): boolean;
+}
+
+export declare type ActionType = "move" | "click" | "doubleClick" | "rightClick" | "type" | "clear" | "focus" | "blur" | "wait" | "scroll" | "scrollTo" | "select" | "check" | "uncheck" | "hover" | "press" | "highlight" | "caption" | "drag" | string;
+
+export declare interface BaseStep {
+    type: ActionType;
+    caption?: string | CaptionOptions;
+    waitForTarget?: number;
+    delayBefore?: number;
+    delayAfter?: number;
+    [key: string]: any;
+}
+
+declare function blur_2(target: DemoTarget, options?: Partial<BlurStep>): BlurStep;
+export { blur_2 as blur }
+
+export declare interface BlurStep extends BaseStep {
+    type: "blur";
+    target: DemoTarget;
+}
+
+export declare function caption(textOrOptions: string | CaptionOptions, target?: DemoTarget): CaptionStep;
+
+export declare interface CaptionOptions {
+    title?: string;
+    text: string;
+    position?: "top" | "bottom" | "left" | "right" | "auto";
+    duration?: number;
+}
+
+export declare interface CaptionStep extends BaseStep {
+    type: "caption";
+    options: CaptionOptions;
+    target?: DemoTarget;
+}
+
+export declare function check(target: DemoTarget, options?: Partial<CheckStep>): CheckStep;
+
+export declare interface CheckStep extends BaseStep {
+    type: "check";
+    target: DemoTarget;
+}
+
+export declare function clear(target: DemoTarget, options?: Partial<ClearStep>): ClearStep;
+
+export declare interface ClearStep extends BaseStep {
+    type: "clear";
+    target: DemoTarget;
+}
+
+export declare function click(target: DemoTarget, options?: Partial<ClickStep>): ClickStep;
+
+export declare interface ClickStep extends BaseStep {
+    type: "click";
+    target: DemoTarget;
+    button?: "left" | "right" | "middle";
+    clickCount?: number;
+}
+
+export declare interface CursorConfig {
+    style?: CursorStyle;
+    customSvg?: string;
+    customElement?: HTMLElement;
+    size?: number;
+    color?: string;
+}
+
+export declare class CursorEngine implements CursorEngineInterface {
+    private element;
+    private pointerMode;
+    private config;
+    private position;
+    private activeAnimation;
+    private activeAnimationResolve;
+    private pendingTimers;
+    private ripples;
+    private container;
+    private deterministic;
+    private prefersReducedMotion;
+    constructor(options?: {
+        pointerMode?: PointerMode;
+        cursor?: CursorConfig;
+        container?: HTMLElement;
+        deterministic?: boolean;
+    });
+    private mount;
+    private renderCursorGraphic;
+    moveTo(x: number, y: number, duration?: number): Promise<void>;
+    click(_button?: string): Promise<void>;
+    doubleClick(): Promise<void>;
+    private createRipple;
+    private wait;
+    private schedule;
+    private removeRipple;
+    private finishActiveAnimation;
+    show(): void;
+    hide(): void;
+    setState(state: "default" | "pointer" | "text" | "active" | "hidden"): void;
+    getPosition(): Point;
+    private updatePosition;
+    destroy(): void;
+}
+
+export declare interface CursorEngineInterface {
+    moveTo(x: number, y: number, duration?: number): Promise<void>;
+    click(button?: string): Promise<void>;
+    doubleClick(): Promise<void>;
+    show(): void;
+    hide(): void;
+    setState(state: "default" | "pointer" | "text" | "active" | "hidden"): void;
+    getPosition(): {
+        x: number;
+        y: number;
+    };
+    destroy(): void;
+}
+
+export declare type CursorStyle = "classic" | "pointer" | "dot" | "minimal" | "custom";
+
+export declare interface CustomTheme {
+    accent?: string;
+    cursor?: string;
+    glassBg?: string;
+    border?: string;
+    text?: string;
+    shadow?: string;
+    zIndexCursor?: number;
+    zIndexOverlay?: number;
+}
+
+export declare interface DemoGhostConfig extends PlaybackOptions {
+    defaultTimeout?: number;
+    typingSpeed?: TypingSpeed;
+}
+
+export declare class DemoGhostConfigurationError extends DemoGhostError {
+    constructor(message: string);
+}
+
+export declare class DemoGhostCore {
+    private static globalConfig;
+    static actions: ActionRegistry;
+    private static globalEmitter;
+    private static activeController;
+    static configure(config: DemoGhostConfig): void;
+    static play(scenarioOrSteps: DemoScenario | DemoStep[], options?: PlaybackOptions): PlaybackController;
+    static create(scenario: DemoScenario, defaultOptions?: PlaybackOptions): {
+        play: (options?: PlaybackOptions) => PlaybackController;
+    };
+    static on<K extends keyof PlaybackEvents>(event: K, listener: (data: PlaybackEvents[K]) => void): () => void;
+    static off<K extends keyof PlaybackEvents>(event: K, listener: (data: PlaybackEvents[K]) => void): void;
+}
+
+export declare class DemoGhostError extends Error {
+    constructor(message: string);
+}
+
+export declare class DemoGhostPlaybackError extends DemoGhostError {
+    readonly stepIndex?: number;
+    constructor(message: string, stepIndex?: number);
+}
+
+export declare class DemoGhostRecordingError extends DemoGhostError {
+    constructor(message: string);
+}
+
+export declare class DemoGhostTargetNotFoundError extends DemoGhostError {
+    readonly target: string;
+    readonly timeout: number;
+    readonly stepIndex?: number;
+    constructor(target: string, timeout: number, stepIndex?: number);
+}
+
+export declare class DemoGhostTimeoutError extends DemoGhostError {
+    readonly condition: string;
+    readonly timeout: number;
+    constructor(condition: string, timeout: number);
+}
+
+export declare interface DemoScenario {
+    id?: string;
+    name?: string;
+    description?: string;
+    version?: number;
+    tags?: string[];
+    steps: DemoStep[];
+}
+
+export declare type DemoStep = MoveStep | ClickStep | DoubleClickStep | RightClickStep | TypeStep | ClearStep | FocusStep | BlurStep | WaitStep | ScrollStep | ScrollToStep | SelectStep | CheckStep | UncheckStep | HoverStep | PressStep | HighlightStep | CaptionStep | DragStep | BaseStep;
+
+export declare type DemoTarget = TargetSelector | TargetOptions;
+
+export declare type DemoTheme = ThemeName | CustomTheme;
+
+export declare function doubleClick(target: DemoTarget, options?: Partial<DoubleClickStep>): DoubleClickStep;
+
+export declare interface DoubleClickStep extends BaseStep {
+    type: "doubleClick";
+    target: DemoTarget;
+}
+
+export declare function drag(source: DemoTarget, target: DemoTarget, options?: Partial<DragStep>): DragStep;
+
+export declare interface DragStep extends BaseStep {
+    type: "drag";
+    source: DemoTarget;
+    target: DemoTarget;
+    duration?: number;
+}
+
+export declare class EventEmitter<Events extends Record<string, any>> {
+    private listeners;
+    on<K extends keyof Events>(event: K, listener: (data: Events[K]) => void): () => void;
+    off<K extends keyof Events>(event: K, listener: (data: Events[K]) => void): void;
+    emit<K extends keyof Events>(event: K, data: Events[K]): void;
+    removeAllListeners(): void;
+}
+
+declare function focus_2(target: DemoTarget, options?: Partial<FocusStep>): FocusStep;
+export { focus_2 as focus }
+
+export declare interface FocusStep extends BaseStep {
+    type: "focus";
+    target: DemoTarget;
+}
+
+export declare function highlight(target: DemoTarget, options?: Partial<HighlightStep>): HighlightStep;
+
+export declare interface HighlightStep extends BaseStep {
+    type: "highlight";
+    target: DemoTarget;
+    duration?: number;
+    style?: "glow" | "spotlight" | "outline" | "pulse";
+}
+
+export declare function hover(target: DemoTarget, duration?: number, options?: Partial<HoverStep>): HoverStep;
+
+export declare interface HoverStep extends BaseStep {
+    type: "hover";
+    target: DemoTarget;
+    duration?: number;
+}
+
+export declare function move(target: DemoTarget, options?: Partial<MoveStep>): MoveStep;
+
+export declare interface MoveStep extends BaseStep {
+    type: "move";
+    target: DemoTarget;
+    duration?: number;
+}
+
+export declare class PlaybackController implements PlaybackControllerInterface {
+    private scenario;
+    private options;
+    private actionRegistry;
+    private emitter;
+    private _state;
+    private _currentStep;
+    private _speed;
+    private abortController;
+    private pauseResolver;
+    private runPromise;
+    private enginesInitialized;
+    private finishResolver;
+    private finishRejecter;
+    finished: Promise<void>;
+    private targetResolver;
+    private cursorEngine;
+    private scrollEngine;
+    private spotlightEngine;
+    private a11y;
+    constructor(scenario: DemoScenario, options: PlaybackOptions | undefined, actionRegistry: ActionRegistry, emitter?: EventEmitter<PlaybackEvents>);
+    private initEngines;
+    private resetFinishedPromise;
+    get state(): PlaybackState;
+    get currentStep(): number;
+    get totalSteps(): number;
+    get speed(): number;
+    set speed(val: number);
+    play(): Promise<void>;
+    private runPlayback;
+    private executeStep;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    restart(): Promise<void>;
+    next(): Promise<void>;
+    previous(): Promise<void>;
+    private waitIfPaused;
+    private waitForDuration;
+    private cleanup;
+    then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private log;
+    on<K extends keyof PlaybackEvents>(event: K, listener: (data: PlaybackEvents[K]) => void): () => void;
+    off<K extends keyof PlaybackEvents>(event: K, listener: (data: PlaybackEvents[K]) => void): void;
+}
+
+export declare interface PlaybackControllerInterface extends PromiseLike<void> {
+    readonly state: PlaybackState;
+    readonly currentStep: number;
+    readonly totalSteps: number;
+    readonly finished: Promise<void>;
+    speed: number;
+    play(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    restart(): Promise<void>;
+    next(): Promise<void>;
+    previous(): Promise<void>;
+    on<K extends keyof PlaybackEvents>(event: K, listener: (data: PlaybackEvents[K]) => void): () => void;
+    off<K extends keyof PlaybackEvents>(event: K, listener: (data: PlaybackEvents[K]) => void): void;
+}
+
+export declare interface PlaybackEvents {
+    start: {
+        scenario: DemoScenario;
+    };
+    "step:start": {
+        step: DemoStep;
+        index: number;
+        total: number;
+    };
+    "step:complete": {
+        step: DemoStep;
+        index: number;
+        total: number;
+    };
+    pause: void;
+    resume: void;
+    complete: {
+        scenario: DemoScenario;
+    };
+    stop: void;
+    error: {
+        error: Error;
+        stepIndex?: number;
+    };
+    "record:start": void;
+    "record:stop": {
+        scenario: DemoScenario;
+    };
+}
+
+export declare interface PlaybackOptions {
+    speed?: number;
+    typingSpeed?: TypingSpeed;
+    defaultTimeout?: number;
+    pointer?: PointerMode;
+    cursor?: CursorConfig;
+    scroll?: ScrollConfig;
+    theme?: DemoTheme;
+    controls?: boolean;
+    debug?: boolean;
+    autoStart?: boolean;
+    loop?: boolean;
+    deterministic?: boolean;
+    container?: HTMLElement;
+}
+
+export declare type PlaybackState = "idle" | "playing" | "paused" | "completed" | "stopped" | "error";
+
+declare interface Point {
+    x: number;
+    y: number;
+}
+
+export declare type PointerMode = "cursor" | "touch";
+
+export declare function press(key: string, options?: Partial<PressStep>): PressStep;
+
+export declare interface PressStep extends BaseStep {
+    type: "press";
+    key: string;
+    target?: DemoTarget;
+}
+
+export declare function rightClick(target: DemoTarget, options?: Partial<RightClickStep>): RightClickStep;
+
+export declare interface RightClickStep extends BaseStep {
+    type: "rightClick";
+    target: DemoTarget;
+}
+
+declare function scroll_2(targetOrOptions?: DemoTarget | Partial<ScrollStep>, options?: Partial<ScrollStep>): ScrollStep;
+export { scroll_2 as scroll }
+
+export declare interface ScrollConfig {
+    behavior?: ScrollBehavior;
+    offset?: number;
+}
+
+export declare class ScrollEngine implements ScrollEngineInterface {
+    private config;
+    private activeScroll;
+    constructor(config?: ScrollConfig);
+    scrollIntoView(element: HTMLElement, customOffset?: number): Promise<void>;
+    scrollTo(x: number, y: number, behavior?: ScrollBehavior): Promise<void>;
+    private finishActiveScroll;
+    destroy(): void;
+}
+
+export declare interface ScrollEngineInterface {
+    scrollIntoView(element: HTMLElement, offset?: number): Promise<void>;
+    scrollTo(x: number, y: number, behavior?: ScrollBehavior): Promise<void>;
+    destroy(): void;
+}
+
+export declare interface ScrollStep extends BaseStep {
+    type: "scroll";
+    target?: DemoTarget;
+    x?: number;
+    y?: number;
+    offset?: number;
+    behavior?: ScrollBehavior;
+}
+
+declare function scrollTo_2(x: number, y: number, behavior?: ScrollBehavior): ScrollToStep;
+export { scrollTo_2 as scrollTo }
+
+export declare interface ScrollToStep extends BaseStep {
+    type: "scrollTo";
+    x: number;
+    y: number;
+    behavior?: ScrollBehavior;
+}
+
+export declare function select(target: DemoTarget, value: string | string[], options?: Partial<SelectStep>): SelectStep;
+
+export declare interface SelectStep extends BaseStep {
+    type: "select";
+    target: DemoTarget;
+    value: string | string[];
+}
+
+export declare class SpotlightEngine implements SpotlightEngineInterface {
+    private container;
+    private overlayEl;
+    private captionEl;
+    private activeElement;
+    private activeStyle;
+    private activeTimer;
+    private activeTimerResolve;
+    constructor(container?: HTMLElement);
+    highlight(element: HTMLElement, options?: {
+        duration?: number;
+        style?: string;
+        caption?: CaptionOptions | string;
+    }): Promise<void>;
+    clearHighlight(): void;
+    private renderSpotlightOverlay;
+    showCaption(options: CaptionOptions, targetEl?: HTMLElement): void;
+    hideCaption(): void;
+    private escapeHtml;
+    destroy(): void;
+}
+
+export declare interface SpotlightEngineInterface {
+    highlight(element: HTMLElement, options?: {
+        duration?: number;
+        style?: string;
+        caption?: CaptionOptions | string;
+    }): Promise<void>;
+    clearHighlight(): void;
+    showCaption(options: CaptionOptions, targetEl?: HTMLElement): void;
+    hideCaption(): void;
+    destroy(): void;
+}
+
+export declare interface TargetOptions {
+    selector: TargetSelector;
+    timeout?: number;
+    waitForTarget?: number;
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+}
+
+export declare class TargetResolver implements TargetResolverInterface {
+    private defaultTimeout;
+    constructor(defaultTimeout?: number);
+    resolve(target: DemoTarget, stepIndex?: number, signal?: AbortSignal): Promise<HTMLElement>;
+    resolveOptional(target: DemoTarget, signal?: AbortSignal): Promise<HTMLElement | null>;
+    private normalizeTarget;
+    private find;
+    querySingle(selector: string): HTMLElement | null;
+    private queryByText;
+    private pierceShadow;
+}
+
+export declare interface TargetResolverInterface {
+    resolve(target: DemoTarget, stepIndex?: number, signal?: AbortSignal): Promise<HTMLElement>;
+    resolveOptional(target: DemoTarget, signal?: AbortSignal): Promise<HTMLElement | null>;
+}
+
+export declare type TargetSelector = string | HTMLElement;
+
+export declare class ThemeManager {
+    static apply(theme?: DemoTheme, container?: HTMLElement): void;
+}
+
+export declare type ThemeName = "auto" | "light" | "dark" | "glass";
+
+export declare function type(target: DemoTarget, value: string, options?: Partial<TypeStep>): TypeStep;
+
+export declare interface TypeStep extends BaseStep {
+    type: "type";
+    target: DemoTarget;
+    value: string;
+    speed?: TypingSpeed;
+    clearFirst?: boolean;
+}
+
+export declare type TypingSpeed = "instant" | "fast" | "normal" | "slow" | "human" | number;
+
+export declare function uncheck(target: DemoTarget, options?: Partial<UncheckStep>): UncheckStep;
+
+export declare interface UncheckStep extends BaseStep {
+    type: "uncheck";
+    target: DemoTarget;
+}
+
+export declare function wait(durationOrCondition: number | (() => boolean | Promise<boolean>), options?: Partial<WaitStep>): WaitStep;
+
+export declare function waitFor(targetOrSelectorOrCondition: string | (() => boolean | Promise<boolean>) | {
+    selector: string;
+    state?: "visible" | "hidden" | "attached" | "detached";
+    timeout?: number;
+}, options?: Partial<WaitStep>): WaitStep;
+
+export declare interface WaitStep extends BaseStep {
+    type: "wait";
+    duration?: number;
+    condition?: () => boolean | Promise<boolean>;
+    selector?: string;
+    state?: "visible" | "hidden" | "attached" | "detached";
+    timeout?: number;
+}
+
+
+
+
+export declare class DemoGhostRecorder {
+    static record(options?: RecorderOptions): EventRecorder;
+    static serialize(scenario: DemoScenario): string;
+    static deserialize(json: string): DemoScenario;
+    static toTypeScript(scenario: DemoScenario): string;
+    static toJavaScript(scenario: DemoScenario): string;
+}
+
+export declare class EventRecorder {
+    private options;
+    private selectorGen;
+    private privacyMasker;
+    private steps;
+    private isRecording;
+    private lastActionTime;
+    private activeInputTimer;
+    private activeInputElement;
+    private activeInputValue;
+    private clickListener;
+    private inputListener;
+    private changeListener;
+    private scrollListener;
+    private keydownListener;
+    constructor(options?: RecorderOptions);
+    start(): void;
+    stop(): DemoScenario;
+    private bindEvents;
+    private unbindEvents;
+    private appendWaitIfNecessary;
+    private handleClick;
+    private handleInput;
+    private flushActiveInput;
+    private handleChange;
+    private handleKeydown;
+    private isTextEntryElement;
+    private handleScroll;
+}
+
+export declare class PrivacyMasker {
+    private maskPasswords;
+    private maskSelectors;
+    private ignoreSelectors;
+    constructor(options?: PrivacyOptions);
+    shouldIgnore(element: HTMLElement): boolean;
+    isSensitive(element: HTMLElement): boolean;
+    maskValue(element: HTMLElement, originalValue: string): string;
+}
+
+export declare interface PrivacyOptions {
+    maskPasswords?: boolean;
+    maskSelectors?: string[];
+    ignoreSelectors?: string[];
+}
+
+export declare interface RecorderOptions {
+    selector?: SelectorOptions;
+    privacy?: PrivacyOptions;
+    maskPasswords?: boolean;
+    maskSelectors?: string[];
+    ignoreSelectors?: string[];
+    captureScroll?: boolean;
+    captureKeyboard?: boolean;
+    minWaitDuration?: number;
+}
+
+export declare class ScenarioSerializer {
+    static serialize(scenario: DemoScenario): string;
+    static deserialize(json: string): DemoScenario;
+    static toTypeScript(scenario: DemoScenario): string;
+    static toJavaScript(scenario: DemoScenario): string;
+    private static formatStepCode;
+    private static formatOptions;
+    private static pickOptions;
+    private static formatValue;
+}
+
+export declare class SelectorGenerator {
+    private preferredAttributes;
+    private ignoreClasses;
+    private maxDepth;
+    constructor(options?: SelectorOptions);
+    generate(element: HTMLElement): string;
+    private getContextualSelector;
+    private isValidId;
+    private isUnique;
+    private getUniqueClassSelector;
+    private getHierarchicalPath;
+}
+
+export declare interface SelectorOptions {
+    preferredAttributes?: string[];
+    ignoreClasses?: string[];
+    maxDepth?: number;
+}
+
+
+
+
+export declare function attachControls(controller: PlaybackControllerInterface, options?: ControlsOptions): DemoGhostControls;
+
+export declare interface ControlsOptions {
+    container?: HTMLElement;
+    showStepBadge?: boolean;
+    showProgress?: boolean;
+    showSpeed?: boolean;
+}
+
+export declare class DemoGhostControls {
+    private controller;
+    private options;
+    private rootElement;
+    private unsubs;
+    constructor(controller: PlaybackControllerInterface, options?: ControlsOptions);
+    private mount;
+    private render;
+    private attachListeners;
+    private bindEvents;
+    destroy(immediate?: boolean): void;
+}
+
+
+
+
+export declare class DemoGhost {
+    static actions: ActionRegistry;
+    static configure(config: DemoGhostConfig): void;
+    static play(scenarioOrSteps: DemoScenario | DemoStep[], options?: PlaybackOptions): PlaybackController;
+    static record(options?: RecorderOptions): EventRecorder;
+    static create(scenario: DemoScenario, defaultOptions?: PlaybackOptions): {
+        play: (options?: PlaybackOptions) => PlaybackController;
+    };
+    static serialize(scenario: DemoScenario): string;
+    static deserialize(json: string): DemoScenario;
+    static toTypeScript(scenario: DemoScenario): string;
+    static toJavaScript(scenario: DemoScenario): string;
+    static export(scenario: DemoScenario, format?: "json" | "ts" | "js"): string;
+    static on<K extends keyof PlaybackEvents>(event: K, listener: (data: PlaybackEvents[K]) => void): () => void;
+    static off<K extends keyof PlaybackEvents>(event: K, listener: (data: PlaybackEvents[K]) => void): void;
+    static move: typeof move;
+    static click: typeof click;
+    static doubleClick: typeof doubleClick;
+    static rightClick: typeof rightClick;
+    static type: typeof type;
+    static clear: typeof clear;
+    static focus: typeof focus;
+    static blur: typeof blur;
+    static wait: typeof wait;
+    static waitFor: typeof waitFor;
+    static scroll: typeof scroll;
+    static scrollTo: typeof scrollTo;
+    static select: typeof select;
+    static check: typeof check;
+    static uncheck: typeof uncheck;
+    static hover: typeof hover;
+    static press: typeof press;
+    static highlight: typeof highlight;
+    static caption: typeof caption;
+    static drag: typeof drag;
+}
+
+export default DemoGhost;