lib-e2e-cypress-for-dummys-ts 0.3.0 → 0.6.0

package/dist/index.d.cts

@@ -1,6 +1,10 @@
 type Lang = 'es' | 'en' | 'fr' | 'it' | 'de';
 declare const SUPPORTED_LANGS: Lang[];
 declare function isLang(value: string): value is Lang;
+/** BCP-47 locale used for date/number formatting per UI language. */
+declare const LOCALE_BY_LANG: Record<Lang, string>;
+/** Returns the formatting locale for a UI language (falls back to es-ES). */
+declare function localeForLang(lang: string): string;
 
 declare const INPUT_TYPES: readonly ["text", "password", "email", "search", "tel", "url", "number", "textarea"];
 type InputType = (typeof INPUT_TYPES)[number];
@@ -22,51 +26,7 @@ interface DBSchema {
     stores: DBStore[];
 }
 declare const DB_SCHEMA: DBSchema;
-declare const DB_STORE_NAMES: ["tests", "commands", "interceptors", "configuration"];
-
-declare class TranslationService {
-    private lang;
-    private readonly translations;
-    constructor();
-    setLang(lang: Lang): void;
-    getLang(): Lang;
-    translate(key: string): string;
-    detectLang(): Lang;
-}
-declare const translationService: TranslationService;
-
-declare class TransformationService {
-    toLang(lang: string): Lang;
-    generateItDescription(description: string, commands: string[]): string;
-}
-declare const transformationService: TransformationService;
-
-interface DirectoryNode {
-    name: string;
-    kind: 'directory';
-    children: (DirectoryNode | FileNode)[];
-}
-interface FileNode {
-    name: string;
-    kind: 'file';
-}
-declare class AdvancedTestTransformationService {
-    insertBeforeEach(content: string, interceptors: string, alertFn?: (msg: string) => void): string;
-    insertItBlock(content: string, itBlock: string, alertFn?: (msg: string) => void): string;
-    buildBlockComment(notes: string): string;
-    isFile(file: unknown): boolean;
-    scanDirectory(dirHandle: FileSystemDirectoryHandle): Promise<DirectoryNode>;
-}
-declare const advancedTestTransformationService: AdvancedTestTransformationService;
-
-declare class Subject<T> {
-    private _value;
-    private listeners;
-    constructor(initialValue: T);
-    next(value: T): void;
-    getValue(): T;
-    subscribe(fn: (v: T) => void): () => void;
-}
+declare const DB_STORE_NAMES: ["tests", "commands", "interceptors", "configuration", "activeSession"];
 
 type SelectorStrategy = 'data-cy' | 'data-testid' | 'aria-label' | 'id';
 declare class RecordingService {
@@ -78,10 +38,22 @@ declare class RecordingService {
     private readonly inputDebounceTimers;
     private readonly abort;
     selectorStrategy: SelectorStrategy;
+    /** Stable id of the current live session (null when none has started). */
+    sessionId: string | null;
+    private startedAt;
     private readonly origPushState;
     private readonly origReplaceState;
     constructor();
     startRecording(): void;
+    /**
+     * Rehydrates a previously persisted session WITHOUT running the startRecording
+     * bootstrap (no viewport/visit/hide). Used to continue a recording across a
+     * micro-frontend crossing or a same-origin reload.
+     * See docs/specs/006-cross-app-recording-continuity.md.
+     */
+    restoreSession(state: ActiveSessionState): void;
+    /** Full snapshot of the live session for persistence. */
+    getSessionSnapshot(): ActiveSessionState;
     stopRecording(): void;
     toggleRecording(): void;
     pauseRecording(): void;
@@ -103,6 +75,12 @@ declare class RecordingService {
     onInterceptorsChange(fn: (ints: string[]) => void): () => void;
     onRecordingChange(fn: (isRecording: boolean) => void): () => void;
     onPauseChange(fn: (isPaused: boolean) => void): () => void;
+    /**
+     * Fires a full session snapshot whenever any persisted field changes
+     * (commands, interceptors, recording or paused state). Drives the debounced
+     * persistence of the live session. Returns a combined unsubscribe.
+     */
+    onSessionChange(fn: (state: ActiveSessionState) => void): () => void;
     onSelectorNotFound(fn: (target: HTMLElement, action: 'click') => void): () => void;
     destroy(): void;
     private listenToClicks;
@@ -121,6 +99,82 @@ declare class RecordingService {
     private urlToWildcard;
 }
 
+/**
+ * A live, in-progress recording session, persisted so it can survive a
+ * micro-frontend crossing (single-spa app swap) or an accidental same-origin
+ * reload. Only an actively-recording session is ever stored/resumed.
+ *
+ * The full payload lives in IndexedDB; a lightweight breadcrumb (sessionId +
+ * isRecording + updatedAt) is mirrored to localStorage for synchronous detection.
+ *
+ * See docs/specs/006-cross-app-recording-continuity.md.
+ */
+interface ActiveSessionState {
+    /** Stable id for the session, generated when recording starts. */
+    sessionId: string;
+    isRecording: boolean;
+    isPaused: boolean;
+    commands: string[];
+    interceptors: string[];
+    selectorStrategy: SelectorStrategy;
+    /** Epoch ms when the session started recording. */
+    startedAt: number;
+    /** Epoch ms of the last mutation — acts as the recency heartbeat. */
+    updatedAt: number;
+}
+/** localStorage key for the synchronous "is a session active?" breadcrumb. */
+declare const ACTIVE_SESSION_BREADCRUMB_KEY = "e2e-active-session";
+/** Configuration key (in the `configuration` store) for the resume recency TTL. */
+declare const RESUME_TTL_CONFIG_KEY = "resumeRecencyTtlMinutes";
+/** Default minutes within which an active session resumes silently. */
+declare const DEFAULT_RESUME_TTL_MINUTES = 30;
+
+declare class TranslationService {
+    private readonly lang$;
+    private readonly translations;
+    constructor();
+    setLang(lang: Lang): void;
+    getLang(): Lang;
+    /** Subscribe to language changes; returns an unsubscribe function. */
+    onLangChange(fn: (lang: Lang) => void): () => void;
+    translate(key: string): string;
+    detectLang(): Lang;
+}
+declare const translationService: TranslationService;
+
+declare class TransformationService {
+    toLang(lang: string): Lang;
+    generateItDescription(description: string, commands: string[]): string;
+}
+declare const transformationService: TransformationService;
+
+interface DirectoryNode {
+    name: string;
+    kind: 'directory';
+    children: (DirectoryNode | FileNode)[];
+}
+interface FileNode {
+    name: string;
+    kind: 'file';
+}
+declare class AdvancedTestTransformationService {
+    insertBeforeEach(content: string, interceptors: string, alertFn?: (msg: string) => void): string;
+    insertItBlock(content: string, itBlock: string, alertFn?: (msg: string) => void): string;
+    buildBlockComment(notes: string): string;
+    isFile(file: unknown): boolean;
+    scanDirectory(dirHandle: FileSystemDirectoryHandle): Promise<DirectoryNode>;
+}
+declare const advancedTestTransformationService: AdvancedTestTransformationService;
+
+declare class Subject<T> {
+    private _value;
+    private listeners;
+    constructor(initialValue: T);
+    next(value: T): void;
+    getValue(): T;
+    subscribe(fn: (v: T) => void): () => void;
+}
+
 interface TestRecord {
     id: number;
     name: string;
@@ -174,6 +228,12 @@ declare class PersistenceService {
     setConfigKey(key: string, value: unknown): Promise<void>;
     getConfig(key: string): Promise<Record<string, unknown> | null>;
     getGeneralConfig(): Promise<ConfigRecord | null>;
+    /** Upserts the live recording session (single record, fixed key). */
+    saveActiveSession(state: ActiveSessionState): Promise<void>;
+    /** Returns the persisted live session, or null when none is stored. */
+    getActiveSession(): Promise<ActiveSessionState | null>;
+    /** Removes the live session record. Safe to call when none exists. */
+    clearActiveSession(): Promise<void>;
     clearAllData(): Promise<void>;
     ingestFileData(tests: Record<string, unknown>[], interceptors: Record<string, unknown>[]): Promise<void>;
     requestDirectoryPermissions(): Promise<void>;
@@ -212,6 +272,95 @@ declare function setSwal2DataCyAttribute(dataCy?: string): void;
 
 declare function showToast(message: string, isSuccess?: boolean): void;
 
+/** How the user chose which tests to export. */
+type ExportMode = 'all' | 'manual' | 'tags';
+interface ExportSelectionOptions {
+    /** Test ids to include in `manual` mode. */
+    ids?: Iterable<number>;
+    /** Tags to match in `tags` mode. */
+    tags?: Iterable<string>;
+}
+/**
+ * Returns the subset of tests to export for a given selection mode.
+ *
+ * - `all`    → every test (a shallow copy).
+ * - `manual` → tests whose id is in `opts.ids`. Empty/absent ids → none.
+ * - `tags`   → tests carrying at least one of `opts.tags` (OR semantics).
+ *              Empty/absent tags → none.
+ *
+ * Pure: never mutates its inputs.
+ */
+declare function selectTestsForExport(tests: TestWithDetails[], mode: ExportMode, opts?: ExportSelectionOptions): TestWithDetails[];
+
+/**
+ * True when a hostname refers to the local machine — used to gate dev-only
+ * features (e.g. launching a Cypress run via the local runner) so they are
+ * offered only when the app is served locally, not from a deployed environment.
+ *
+ * Treats as local: localhost, *.localhost, 127.0.0.1, ::1, 0.0.0.0, and the
+ * empty hostname (e.g. file:// URLs). Case-insensitive.
+ */
+declare function isLocalHost(hostname: string): boolean;
+
+/**
+ * Geometry helpers for the draggable recording widget (spec 007).
+ * Pure functions — no DOM — so the drag/clamp/expansion logic is unit-testable
+ * without real layout (jsdom returns 0-sized rects).
+ */
+type ExpandDirection = 'up-left' | 'up-right' | 'down-left' | 'down-right';
+interface Point {
+    x: number;
+    y: number;
+}
+/** Toggle radius (44/2) + small gap, so the toggle never touches the edge. */
+declare const TOGGLE_MARGIN = 30;
+/** Pixels the pointer must travel before a press becomes a drag (vs a click). */
+declare const DRAG_THRESHOLD = 5;
+/**
+ * Toggle-centre offset inside the 190×190 widget box, per expansion direction.
+ * The toggle sits at the box corner nearest the screen edge so the arc always
+ * expands toward the viewport interior (and stays inside the box / on screen).
+ */
+declare function boxOffsetForDirection(dir: ExpandDirection): Point;
+/** Clamps the toggle-centre so the toggle button stays fully on screen. */
+declare function clampTogglePosition(x: number, y: number, vw: number, vh: number, margin?: number): Point;
+/**
+ * Chooses the radial expansion direction so the menu opens toward the centre of
+ * the viewport (top half → expand down; left half → expand right).
+ */
+declare function resolveExpandDirection(x: number, y: number, vw: number, vh: number): ExpandDirection;
+/** Default toggle-centre (bottom-right corner), matching the original CSS anchor. */
+declare function defaultTogglePosition(vw: number, vh: number): Point;
+/** Box top-left for a given (clamped) toggle-centre and direction. */
+declare function boxTopLeftFor(toggleCentre: Point, dir: ExpandDirection): Point;
+
+declare class SelectorPickerElement extends HTMLElement {
+    targetElement: HTMLElement | null;
+    recording: RecordingService;
+    translation: TranslationService;
+    private shadow;
+    private ancestors;
+    private rows;
+    private selectedIndex;
+    private keyHandler;
+    private unsubRecording;
+    private unsubPause;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private t;
+    private buildAncestors;
+    private findBestIndex;
+    private render;
+    private attachKeyListener;
+    private detachKeyListener;
+    private attachRowClickListeners;
+    private subscribeToRecordingChanges;
+    private confirm;
+    private cancel;
+    private closeSilently;
+}
+
 declare class TestPrevisualizerElement extends HTMLElement {
     private shadow;
     private _commands;
@@ -294,6 +443,12 @@ declare class ConfigurationElement extends HTMLElement {
     selectorStrategy: SelectorStrategy;
     smartSelectorEnabled: boolean;
     startHidden: boolean;
+    resumeTtlMinutes: number;
+    isExporting: boolean;
+    exportMode: ExportMode;
+    exportTests: TestWithDetails[];
+    exportSelectedIds: Set<number>;
+    exportSelectedTags: Set<string>;
     private filesystemGranted;
     private cypressFolderName;
     constructor();
@@ -303,11 +458,23 @@ declare class ConfigurationElement extends HTMLElement {
     onLanguageChange(lang: string): Promise<void>;
     onAdvancedHttpConfigChange(checked: boolean): void;
     onStartHiddenChange(checked: boolean): Promise<void>;
+    onResumeTtlChange(minutes: number): Promise<void>;
+    onResetWidgetPosition(): void;
     onSmartSelectorChange(enabled: boolean): Promise<void>;
     onSelectorStrategyChange(strategy: SelectorStrategy): Promise<void>;
     changeFolder(): Promise<void>;
     revokeAccess(): Promise<void>;
+    private downloadTests;
+    /** Downloads every saved test (used by the "Todo" mode and as a direct API). */
     exportAllData(): Promise<void>;
+    /** Opens the export selection dialog, loading the current tests. */
+    openExportDialog(): Promise<void>;
+    cancelExport(): void;
+    setExportMode(mode: ExportMode): void;
+    toggleExportTest(id: number): void;
+    toggleExportTag(tag: string): void;
+    /** Downloads the tests resolved by the current mode + selection. No-op if empty. */
+    confirmExport(): void;
     importAllData(file: File): Promise<void>;
     private render;
 }
@@ -330,6 +497,7 @@ declare class AdvancedTestEditorElement extends HTMLElement {
     previewFileName: string | null;
     previewFileContent: string | null;
     isCreatingFile: boolean;
+    isCreatingFolder: boolean;
     collapsedDirs: Set<string>;
     sidebarWidth: number;
     private hasPermission;
@@ -342,6 +510,7 @@ declare class AdvancedTestEditorElement extends HTMLElement {
     private init;
     getFoldersData(): Promise<void>;
     createNewFile(rawName: string): Promise<void>;
+    createNewFolder(rawName: string): Promise<void>;
     refreshTree(): Promise<void>;
     saveCommandsToFile(): Promise<void>;
     onFileClick(file: unknown): Promise<void>;
@@ -363,11 +532,18 @@ declare class FilePreviewElement extends HTMLElement {
     translation: TranslationService;
     itBlock: string;
     interceptorsBlock: string;
+    notes: string;
     commands: string[];
     interceptors: string[];
+    /** Endpoint of the local Cypress runner. Configurable; defaults to the bundled runner's port. */
+    runnerUrl: string;
+    /** Whether the app is served locally — gates the launch button. Overridable for tests. */
+    isLocal: boolean;
     private _fileContent;
     private _originalContent;
     private _showDiff;
+    private _runState;
+    private _runOutput;
     constructor();
     connectedCallback(): void;
     private t;
@@ -375,9 +551,21 @@ declare class FilePreviewElement extends HTMLElement {
     set fileContent(v: string | null);
     saveFile(): void;
     onClose(): void;
+    /**
+     * Runs the current spec headless via the local runner and shows the result.
+     * No-op off localhost. Never throws — connection failures surface as an
+     * "error" state + toast instead of an unhandled rejection.
+     */
     launchTest(specPath?: string): Promise<void>;
     copyToClipboard(text: string): void;
     toggleDiff(): void;
+    /**
+     * Merges the it() and beforeEach() blocks into the current editor content
+     * using the same logic as the automatic "Insert into file" action, so the
+     * user does not have to copy/paste manually. Leaves the content untouched
+     * (and warns) when the file has no valid describe() block to insert into.
+     */
+    insertBlocks(): void;
     private render;
 }
 
@@ -390,7 +578,17 @@ declare class LibE2eRecorderElement extends HTMLElement {
     private interceptorsUnsub?;
     private pauseUnsub?;
     private selectorNotFoundUnsub?;
+    private langUnsub?;
+    private sessionUnsub?;
+    private sessionSaveTimer?;
     private controlFirstTimeData;
+    private togglePos;
+    private expandDir;
+    private dragState?;
+    private suppressNextToggleClick;
+    private widgetPointerMove?;
+    private widgetPointerUp?;
+    private widgetResize?;
     private _previsualizerRef;
     private httpMonitor?;
     private smartSelectorEnabled;
@@ -416,6 +614,36 @@ declare class LibE2eRecorderElement extends HTMLElement {
     private showSelectorPicker;
     private initVisibility;
     private initSelectorStrategy;
+    /**
+     * On mount, detect a persisted live recording session and either resume it
+     * silently (recent) or prompt continue/discard (stale). No-op when there is
+     * no actively-recording session.
+     */
+    private initSessionContinuity;
+    private getResumeTtlMinutes;
+    /** Rehydrates the recorder from a persisted session (no bootstrap re-emitted). */
+    private resumeSessionState;
+    private promptResumeOrDiscard;
+    /** Debounced persistence of the live session; clears it the moment recording stops. */
+    private persistActiveSession;
+    private writeSessionBreadcrumb;
+    private flushActiveSessionOnDisconnect;
+    private clearSessionPersistence;
+    /** True when a synchronous breadcrumb marks an active recording session. */
+    hasActiveSession(): boolean;
+    /** Programmatically resume the persisted session, if any. */
+    resumeSession(): void;
+    /** Discard the persisted live session (breadcrumb + DB record). */
+    discardSession(): void;
+    /** Loads a previously saved widget position and applies it. */
+    private initWidgetPosition;
+    /** Positions the `.widget` box from the (clamped) toggle centre and orients the arc. */
+    private applyWidgetPosition;
+    private beginWidgetDrag;
+    private onWidgetPointerMove;
+    private onWidgetPointerUp;
+    /** Resets the widget to its default corner and clears the saved position. */
+    resetWidgetPosition(): void;
     toggle(): void;
     togglePause(): void;
     setLanguage(lang?: string): void;
@@ -444,6 +672,6 @@ declare class LibE2eRecorderElement extends HTMLElement {
     private render;
 }
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.6.0";
 
-export { AdvancedTestEditorElement, AdvancedTestTransformationService, ConfigurationElement, type DBSchema, type DBStore, type DBStoreIndex, DB_SCHEMA, DB_STORE_NAMES, type DirectoryNode, type FileNode, FilePreviewElement, HttpMonitor, INPUT_TYPES, type InputType, LIB_E2E_CYPRESS_FOR_DUMMYS_SWAL2_STYLES, type Lang, LibE2eRecorderElement, PersistenceService, RecordingService, SCROLLBAR_STYLES, SUPPORTED_LANGS, SaveTestElement, type SelectorStrategy, Subject, type TestDetail, TestEditorElement, TestPrevisualizerElement, type TestWithDetails, TransformationService, TranslationService, VERSION, advancedTestTransformationService, generateAlias, injectStyles, isLang, makeModalResizable, makeSwalDraggable, makeSwalDraggableByContentId, persistenceService, setSwal2DataCyAttribute, showToast, transformationService, translationService };
+export { ACTIVE_SESSION_BREADCRUMB_KEY, type ActiveSessionState, AdvancedTestEditorElement, AdvancedTestTransformationService, ConfigurationElement, type DBSchema, type DBStore, type DBStoreIndex, DB_SCHEMA, DB_STORE_NAMES, DEFAULT_RESUME_TTL_MINUTES, DRAG_THRESHOLD, type DirectoryNode, type ExpandDirection, type ExportMode, type ExportSelectionOptions, type FileNode, FilePreviewElement, HttpMonitor, INPUT_TYPES, type InputType, LIB_E2E_CYPRESS_FOR_DUMMYS_SWAL2_STYLES, LOCALE_BY_LANG, type Lang, LibE2eRecorderElement, PersistenceService, type Point, RESUME_TTL_CONFIG_KEY, RecordingService, SCROLLBAR_STYLES, SUPPORTED_LANGS, SaveTestElement, SelectorPickerElement, type SelectorStrategy, Subject, TOGGLE_MARGIN, type TestDetail, TestEditorElement, TestPrevisualizerElement, type TestWithDetails, TransformationService, TranslationService, VERSION, advancedTestTransformationService, boxOffsetForDirection, boxTopLeftFor, clampTogglePosition, defaultTogglePosition, generateAlias, injectStyles, isLang, isLocalHost, localeForLang, makeModalResizable, makeSwalDraggable, makeSwalDraggableByContentId, persistenceService, resolveExpandDirection, selectTestsForExport, setSwal2DataCyAttribute, showToast, transformationService, translationService };