lib-e2e-cypress-for-dummys-ts 0.2.0 → 0.5.0

package/dist/index.d.ts

@@ -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,50 +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;
-    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 {
@@ -77,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;
@@ -102,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;
@@ -120,11 +99,88 @@ 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;
     createdAt: number;
     tags?: string[];
+    notes?: string;
 }
 interface CommandRecord {
     id: number;
@@ -156,7 +212,7 @@ declare class PersistenceService {
     private _db;
     constructor(dbName?: string);
     private getDB;
-    insertTest(name: string, commands?: string[], interceptors?: string[], tags?: string[]): Promise<number>;
+    insertTest(name: string, commands?: string[], interceptors?: string[], tags?: string[], notes?: string): Promise<number>;
     getAllTests(): Promise<TestWithDetails[]>;
     getTestById(testId: number): Promise<TestDetail | null>;
     deleteTest(id: number): Promise<void>;
@@ -172,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>;
@@ -210,6 +272,63 @@ 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;
+
+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;
@@ -238,6 +357,7 @@ declare class SaveTestElement extends HTMLElement {
     private shadow;
     private _step;
     description: string;
+    notes: string;
     tags: string[];
     translation: TranslationService;
     constructor();
@@ -290,6 +410,13 @@ declare class ConfigurationElement extends HTMLElement {
     advancedHttpConfig: boolean;
     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();
@@ -298,11 +425,23 @@ declare class ConfigurationElement extends HTMLElement {
     private loadConfig;
     onLanguageChange(lang: string): Promise<void>;
     onAdvancedHttpConfigChange(checked: boolean): void;
+    onStartHiddenChange(checked: boolean): Promise<void>;
+    onResumeTtlChange(minutes: number): Promise<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;
 }
@@ -320,10 +459,12 @@ declare class AdvancedTestEditorElement extends HTMLElement {
     selectedFileContent: string | null;
     testItBlock: string;
     interceptorsBlock: string;
+    testNotes: string;
     isPreviewMode: boolean;
     previewFileName: string | null;
     previewFileContent: string | null;
     isCreatingFile: boolean;
+    isCreatingFolder: boolean;
     collapsedDirs: Set<string>;
     sidebarWidth: number;
     private hasPermission;
@@ -336,6 +477,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>;
@@ -357,11 +499,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;
@@ -369,9 +518,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;
 }
 
@@ -384,6 +545,9 @@ declare class LibE2eRecorderElement extends HTMLElement {
     private interceptorsUnsub?;
     private pauseUnsub?;
     private selectorNotFoundUnsub?;
+    private langUnsub?;
+    private sessionUnsub?;
+    private sessionSaveTimer?;
     private controlFirstTimeData;
     private _previsualizerRef;
     private httpMonitor?;
@@ -391,6 +555,7 @@ declare class LibE2eRecorderElement extends HTMLElement {
     recording: RecordingService;
     persistence: PersistenceService;
     translation: TranslationService;
+    isVisible: boolean;
     isRecording: boolean;
     isPaused: boolean;
     cypressCommands: string[];
@@ -407,11 +572,34 @@ declare class LibE2eRecorderElement extends HTMLElement {
     private initLanguage;
     private initSubscriptions;
     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;
     toggle(): void;
     togglePause(): void;
     setLanguage(lang?: string): void;
     handleKeyboardEvent(event: KeyboardEvent): void;
+    toggleVisibility(): void;
     private saveRecordingHistory;
     recoverLastRecording(): void;
     clearRecordingHistory(): void;
@@ -435,6 +623,6 @@ declare class LibE2eRecorderElement extends HTMLElement {
     private render;
 }
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.5.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, type DirectoryNode, 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, RESUME_TTL_CONFIG_KEY, RecordingService, SCROLLBAR_STYLES, SUPPORTED_LANGS, SaveTestElement, SelectorPickerElement, type SelectorStrategy, Subject, type TestDetail, TestEditorElement, TestPrevisualizerElement, type TestWithDetails, TransformationService, TranslationService, VERSION, advancedTestTransformationService, generateAlias, injectStyles, isLang, isLocalHost, localeForLang, makeModalResizable, makeSwalDraggable, makeSwalDraggableByContentId, persistenceService, selectTestsForExport, setSwal2DataCyAttribute, showToast, transformationService, translationService };