@civitas-cerebrum/element-interactions 0.1.1 → 0.1.2

package/README.md

@@ -240,7 +240,11 @@ test('Complete checkout flow', async ({ steps }) => {
 
 ### 4. Access `repo` directly when needed
 
+Repository methods return `Element` wrappers (not raw Playwright `Locator` objects). For most use cases, the `Steps` API handles this transparently. When using `repo` directly, the `Element` interface provides common methods like `click()`, `fill()`, `textContent()`, etc. To access the underlying Playwright `Locator` (e.g. for Playwright-specific assertions), cast to `WebElement`:
+
 ```ts
+import { WebElement } from '@civitas-cerebrum/element-interactions';
+
 test('Navigate to Forms category', async ({ page, repo, steps }) => {
   await steps.navigateTo('/');
 
@@ -249,21 +253,28 @@ test('Navigate to Forms category', async ({ page, repo, steps }) => {
 
   await steps.verifyAbsence('HomePage', 'categories');
 });
+
+test('Use underlying Locator for advanced assertions', async ({ page, repo }) => {
+  const element = await repo.get(page, 'PageName', 'elementName');
+  const locator = (element as WebElement).locator;
+  await expect(locator).toHaveCSS('color', 'rgb(255, 0, 0)');
+});
 ```
 
 **Full Repository API:**
 
 ```ts
-await repo.get(page, 'PageName', 'elementName');               // single locator
-await repo.getAll(page, 'PageName', 'elementName');             // array of locators
+await repo.get(page, 'PageName', 'elementName');               // single Element
+await repo.getAll(page, 'PageName', 'elementName');             // array of Elements
 await repo.getRandom(page, 'PageName', 'elementName');          // random from matches
-await repo.getByText(page, 'PageName', 'elementName', 'Text'); // filter by visible text
+await repo.getByText(page, 'PageName', 'elementName', 'Text'); // filter by visible text (exact, then contains)
 await repo.getByAttribute(page, 'PageName', 'elementName', 'data-status', 'active'); // filter by attribute
 await repo.getByAttribute(page, 'PageName', 'elementName', 'href', '/path', { exact: false }); // partial match
 await repo.getByIndex(page, 'PageName', 'elementName', 2);     // zero-based index
 await repo.getByRole(page, 'PageName', 'elementName', 'button'); // explicit HTML role attribute
 await repo.getVisible(page, 'PageName', 'elementName');         // first visible match
 repo.getSelector('PageName', 'elementName');                     // sync, returns raw selector string
+repo.getSelectorRaw('PageName', 'elementName');                  // sync, returns { strategy, value }
 repo.setDefaultTimeout(10000);                                   // change default wait timeout
 ```
 
@@ -327,7 +338,7 @@ Every method below automatically fetches the Playwright `Locator` using your `pa
 * **`uncheck(pageName, elementName)`** — Unchecks a checkbox. No-op if already unchecked.
 * **`hover(pageName, elementName)`** — Hovers over an element to trigger dropdowns or tooltips.
 * **`scrollIntoView(pageName, elementName)`** — Smoothly scrolls an element into the viewport.
-* **`dragAndDrop(pageName, elementName, options: DragAndDropOptions)`** — Drags an element to a target element (`{ target: Locator }`), by coordinate offset (`{ xOffset, yOffset }`), or both.
+* **`dragAndDrop(pageName, elementName, options: DragAndDropOptions)`** — Drags an element to a target element (`{ target: Locator | Element }`), by coordinate offset (`{ xOffset, yOffset }`), or both.
 * **`dragAndDropListedElement(pageName, elementName, elementText, options: DragAndDropOptions)`** — Finds a specific element by its text from a list, then drags it to a destination.
 * **`fill(pageName, elementName, text: string)`** — Clears and fills an input field with the provided text.
 * **`uploadFile(pageName, elementName, filePath: string)`** — Uploads a file to an `<input type="file">` element.
@@ -457,13 +468,36 @@ Send and receive emails in your tests. Supports plain text, inline HTML, and HTM
 
 ### Setup
 
-Pass email credentials to `baseFixture` via the options parameter:
+Pass email credentials to `baseFixture` via the options parameter. You can use the split config (recommended) or the legacy combined format:
 
 ```ts
 // tests/fixtures/base.ts
 import { test as base, expect } from '@playwright/test';
 import { baseFixture } from '@civitas-cerebrum/element-interactions';
 
+// Split config (recommended) — configure smtp, imap, or both
+export const test = baseFixture(base, 'tests/data/page-repository.json', {
+  emailCredentials: {
+    smtp: {
+      email: process.env.SENDER_EMAIL!,
+      password: process.env.SENDER_PASSWORD!,
+      host: process.env.SENDER_SMTP_HOST!,
+    },
+    imap: {
+      email: process.env.RECEIVER_EMAIL!,
+      password: process.env.RECEIVER_PASSWORD!,
+    },
+  }
+});
+export { expect };
+```
+
+Only need to send? Provide `smtp` only. Only need to receive? Provide `imap` only. The client will throw a clear error if you call a method that requires the missing credential.
+
+<details>
+<summary>Legacy combined format (still supported)</summary>
+
+```ts
 export const test = baseFixture(base, 'tests/data/page-repository.json', {
   emailCredentials: {
     senderEmail: process.env.SENDER_EMAIL!,
@@ -473,9 +507,10 @@ export const test = baseFixture(base, 'tests/data/page-repository.json', {
     receiverPassword: process.env.RECEIVER_PASSWORD!,
   }
 });
-export { expect };
 ```
 
+</details>
+
 ### Sending Emails
 
 ```ts
@@ -538,6 +573,32 @@ const allEmails = await steps.receiveAllEmails({
 });
 ```
 
+### Marking Emails
+
+Mark emails as read, unread, flagged, unflagged, or archived:
+
+```ts
+import { EmailMarkAction } from '@civitas-cerebrum/element-interactions';
+
+// Mark matching emails as read
+await steps.markEmail(EmailMarkAction.READ, {
+  filters: [{ type: EmailFilterType.SUBJECT, value: 'OTP' }]
+});
+
+// Flag all emails from a sender
+await steps.markEmail(EmailMarkAction.FLAGGED, {
+  filters: [{ type: EmailFilterType.FROM, value: 'noreply@example.com' }]
+});
+
+// Archive emails
+await steps.markEmail(EmailMarkAction.ARCHIVED, {
+  filters: [{ type: EmailFilterType.SUBJECT, value: 'Report' }]
+});
+
+// Mark all emails in folder
+await steps.markEmail(EmailMarkAction.UNREAD);
+```
+
 ### Cleaning the Inbox
 
 Delete emails matching filters, or clean the entire inbox:
@@ -570,6 +631,8 @@ await steps.cleanEmails();
 | `folder` | `string` | `'INBOX'` | IMAP folder to search |
 | `waitTimeout` | `number` | `30000` | Max time (ms) to wait for a match |
 | `pollInterval` | `number` | `3000` | How often (ms) to poll the inbox |
+| `expectedCount` | `number` | — | Specific number of expected results |
+| `maxFetchLimit` | `number` | `50` | Max emails to fetch per polling cycle |
 | `downloadDir` | `string` | `os.tmpdir()/pw-emails` | Where to save the downloaded HTML |
 
 **`ReceivedEmail` return type:**

package/dist/enum/Options.d.ts

@@ -1,4 +1,5 @@
 import { Locator } from '@playwright/test';
+import { Element } from '@civitas-cerebrum/element-repository';
 /**
  * Defines the strategy for selecting an option from a dropdown element.
  */
@@ -50,8 +51,8 @@ export type CountVerifyOptions = {
  * You must provide either a `targetLocator` OR both `xOffset` and `yOffset`.
  */
 export interface DragAndDropOptions {
-    /** The destination element to drop the dragged element onto. */
-    target?: Locator;
+    /** The destination element to drop the dragged element onto. Accepts a Playwright Locator or an Element from the repository. */
+    target?: Locator | Element;
     /** The horizontal offset from the center of the element (positive moves right). */
     xOffset?: number;
     /** The vertical offset from the center of the element (positive moves down). */

package/dist/fixture/BaseFixture.d.ts

@@ -1,6 +1,6 @@
 import { ElementInteractions } from '../interactions/facade/ElementInteractions';
 import { ElementRepository } from '@civitas-cerebrum/element-repository';
-import { EmailCredentials } from '@civitas-cerebrum/email-client';
+import { EmailCredentials, EmailClientConfig } from '@civitas-cerebrum/email-client';
 import { ContextStore } from '@civitas-cerebrum/context-store';
 import { test as base } from '@playwright/test';
 import { Steps } from '../steps/CommonSteps';
@@ -11,7 +11,7 @@ type StepFixture = {
     steps: Steps;
 };
 export interface BaseFixtureOptions {
-    emailCredentials?: EmailCredentials;
+    emailCredentials?: EmailCredentials | EmailClientConfig;
 }
 export declare function baseFixture<T extends {}>(baseTest: ReturnType<typeof base.extend<T>>, locatorPath: string, options?: BaseFixtureOptions): import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & StepFixture, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
 export {};

package/dist/index.d.ts

@@ -6,8 +6,10 @@ export { Extractions } from './interactions/Extraction';
 export { reformatDateString } from './utils/DateUtilities';
 export { Utils } from './utils/ElementUtilities';
 export { ElementInteractions } from './interactions/facade/ElementInteractions';
+export type { Element } from '@civitas-cerebrum/element-repository';
+export { ElementType, WebElement, PlatformElement, isWeb, isPlatform } from '@civitas-cerebrum/element-repository';
 export { Steps } from './steps/CommonSteps';
 export { baseFixture, BaseFixtureOptions } from './fixture/BaseFixture';
 export { EmailClient } from '@civitas-cerebrum/email-client';
-export type { EmailCredentials, EmailFilter, EmailSendOptions, EmailReceiveOptions, ReceivedEmail, } from '@civitas-cerebrum/email-client';
-export { EmailFilterType } from '@civitas-cerebrum/email-client';
+export type { EmailCredentials, EmailClientConfig, SmtpCredentials, ImapCredentials, EmailFilter, EmailSendOptions, EmailReceiveOptions, ReceivedEmail, EmailMarkOptions, } from '@civitas-cerebrum/email-client';
+export { EmailFilterType, EmailMarkAction } from '@civitas-cerebrum/email-client';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EmailFilterType = exports.EmailClient = exports.baseFixture = exports.Steps = exports.ElementInteractions = exports.Utils = exports.reformatDateString = exports.Extractions = exports.Interactions = exports.Verifications = exports.Navigation = void 0;
+exports.EmailMarkAction = exports.EmailFilterType = exports.EmailClient = exports.baseFixture = exports.Steps = exports.isPlatform = exports.isWeb = exports.PlatformElement = exports.WebElement = exports.ElementType = exports.ElementInteractions = exports.Utils = exports.reformatDateString = exports.Extractions = exports.Interactions = exports.Verifications = exports.Navigation = void 0;
 // Enums
 __exportStar(require("./enum/Options"), exports);
 // Supporting Action Classes
@@ -34,6 +34,12 @@ Object.defineProperty(exports, "Utils", { enumerable: true, get: function () { r
 // Element Interactions Facade
 var ElementInteractions_1 = require("./interactions/facade/ElementInteractions");
 Object.defineProperty(exports, "ElementInteractions", { enumerable: true, get: function () { return ElementInteractions_1.ElementInteractions; } });
+var element_repository_1 = require("@civitas-cerebrum/element-repository");
+Object.defineProperty(exports, "ElementType", { enumerable: true, get: function () { return element_repository_1.ElementType; } });
+Object.defineProperty(exports, "WebElement", { enumerable: true, get: function () { return element_repository_1.WebElement; } });
+Object.defineProperty(exports, "PlatformElement", { enumerable: true, get: function () { return element_repository_1.PlatformElement; } });
+Object.defineProperty(exports, "isWeb", { enumerable: true, get: function () { return element_repository_1.isWeb; } });
+Object.defineProperty(exports, "isPlatform", { enumerable: true, get: function () { return element_repository_1.isPlatform; } });
 // Test Steps Facade
 var CommonSteps_1 = require("./steps/CommonSteps");
 Object.defineProperty(exports, "Steps", { enumerable: true, get: function () { return CommonSteps_1.Steps; } });
@@ -45,3 +51,4 @@ var email_client_1 = require("@civitas-cerebrum/email-client");
 Object.defineProperty(exports, "EmailClient", { enumerable: true, get: function () { return email_client_1.EmailClient; } });
 var email_client_2 = require("@civitas-cerebrum/email-client");
 Object.defineProperty(exports, "EmailFilterType", { enumerable: true, get: function () { return email_client_2.EmailFilterType; } });
+Object.defineProperty(exports, "EmailMarkAction", { enumerable: true, get: function () { return email_client_2.EmailMarkAction; } });

package/dist/interactions/Interaction.js

@@ -3,6 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Interactions = void 0;
 const Options_1 = require("../enum/Options");
 const ElementUtilities_1 = require("../utils/ElementUtilities");
+/** Resolves a Locator or Element to a Playwright Locator. */
+function resolveLocator(target) {
+    if ('_type' in target) {
+        return target.locator;
+    }
+    return target;
+}
 /**
  * The `Interactions` class provides a robust set of methods for interacting
  * with DOM elements via Playwright Locators. It abstracts away common boilerplate
@@ -136,9 +143,10 @@ class Interactions {
     async dragAndDrop(locator, options) {
         await this.utils.waitForState(locator, 'visible');
         if (options.target) {
-            await this.utils.waitForState(options.target, 'visible');
+            const target = resolveLocator(options.target);
+            await this.utils.waitForState(target, 'visible');
             if (options.xOffset !== undefined && options.yOffset !== undefined) {
-                const targetBox = await options.target.boundingBox();
+                const targetBox = await target.boundingBox();
                 if (!targetBox) {
                     throw new Error(`[Action] Error -> Unable to get bounding box for target element.`);
                 }
@@ -146,13 +154,13 @@ class Interactions {
                     x: (targetBox.width / 2) + options.xOffset,
                     y: (targetBox.height / 2) + options.yOffset
                 };
-                await locator.dragTo(options.target, {
+                await locator.dragTo(target, {
                     targetPosition,
                     timeout: this.ELEMENT_TIMEOUT
                 });
                 return;
             }
-            await locator.dragTo(options.target, { timeout: this.ELEMENT_TIMEOUT });
+            await locator.dragTo(target, { timeout: this.ELEMENT_TIMEOUT });
             return;
         }
         if (options.xOffset !== undefined && options.yOffset !== undefined) {

package/dist/interactions/facade/ElementInteractions.d.ts

@@ -3,7 +3,7 @@ import { Interactions } from '../Interaction';
 import { Navigation } from '../Navigation';
 import { Verifications } from '../Verification';
 import { Extractions } from '../Extraction';
-import { EmailClient, EmailCredentials } from '@civitas-cerebrum/email-client';
+import { EmailClient, EmailCredentials, EmailClientConfig } from '@civitas-cerebrum/email-client';
 /**
  * A facade class that centralizes package capabilities.
  * It provides access to navigation, interaction, verification,
@@ -23,5 +23,5 @@ export declare class ElementInteractions {
      * @param timeout - Optional global timeout override (in milliseconds) for all interactions and verifications. Defaults to 30000 ms (30 seconds).
      * @param emailCredentials - Optional email credentials to enable the email sub-API.
      */
-    constructor(page: Page, timeout?: number, emailCredentials?: EmailCredentials);
+    constructor(page: Page, timeout?: number, emailCredentials?: EmailCredentials | EmailClientConfig);
 }

package/dist/steps/CommonSteps.d.ts

@@ -1,6 +1,6 @@
 import { Page, Response } from '@playwright/test';
 import { ElementRepository } from '@civitas-cerebrum/element-repository';
-import { EmailCredentials, EmailSendOptions, EmailReceiveOptions, ReceivedEmail, EmailMarkAction, EmailFilter } from '@civitas-cerebrum/email-client';
+import { EmailCredentials, EmailClientConfig, EmailSendOptions, EmailReceiveOptions, ReceivedEmail, EmailMarkAction, EmailFilter } from '@civitas-cerebrum/email-client';
 import { DropdownSelectOptions, TextVerifyOptions, CountVerifyOptions, DragAndDropOptions, ListedElementMatch, VerifyListedOptions, GetListedDataOptions, FillFormValue, GetAllOptions, ScreenshotOptions } from '../enum/Options';
 /**
  * The `Steps` class serves as a unified Facade for test orchestration.
@@ -24,7 +24,7 @@ export declare class Steps {
      * @param timeout - Optional global timeout override (in milliseconds).
      * @param emailCredentials - Optional email credentials to enable the email sub-API.
      */
-    constructor(page: Page, repo: ElementRepository, timeout?: number, emailCredentials?: EmailCredentials);
+    constructor(page: Page, repo: ElementRepository, timeout?: number, emailCredentials?: EmailCredentials | EmailClientConfig);
     /**
      * Navigates the browser to the specified URL.
      * @param url - The URL or path to navigate to (e.g. `'/dashboard'` or `'https://example.com'`).

package/dist/steps/CommonSteps.js

@@ -4,6 +4,14 @@ exports.Steps = void 0;
 const ElementInteractions_1 = require("../interactions/facade/ElementInteractions");
 const ElementUtilities_1 = require("../utils/ElementUtilities");
 const Logger_1 = require("../logger/Logger");
+/**
+ * Extracts the underlying Playwright Locator from an Element wrapper.
+ * This bridges the platform-agnostic Element interface from element-repository
+ * with the Playwright-specific interaction/verification/extraction classes.
+ */
+function toLocator(element) {
+    return element.locator;
+}
 const log = {
     navigate: (0, Logger_1.logger)('navigate'),
     interact: (0, Logger_1.logger)('interact'),
@@ -118,7 +126,7 @@ class Steps {
      */
     async click(pageName, elementName) {
         log.interact('Clicking on "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.click(locator);
     }
     /**
@@ -129,7 +137,7 @@ class Steps {
      */
     async clickWithoutScrolling(pageName, elementName) {
         log.interact('Clicking (no scroll) on "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.clickWithoutScrolling(locator);
     }
     /**
@@ -141,10 +149,10 @@ class Steps {
      */
     async clickRandom(pageName, elementName) {
         log.interact('Clicking a random element from "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.getRandom(this.page, pageName, elementName);
-        if (!locator)
+        const element = await this.repo.getRandom(this.page, pageName, elementName);
+        if (!element)
             throw new Error(`No visible element found for "${elementName}" in "${pageName}"`);
-        await this.interact.click(locator);
+        await this.interact.click(toLocator(element));
     }
     /**
      * Clicks on an element only if it is present in the DOM.
@@ -155,7 +163,7 @@ class Steps {
      */
     async clickIfPresent(pageName, elementName) {
         log.interact('Clicking on "%s" in "%s" (if present)', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         return this.interact.clickIfPresent(locator);
     }
     /**
@@ -166,7 +174,7 @@ class Steps {
      */
     async rightClick(pageName, elementName) {
         log.interact('Right-clicking on "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.rightClick(locator);
     }
     /**
@@ -176,7 +184,7 @@ class Steps {
      */
     async doubleClick(pageName, elementName) {
         log.interact('Double-clicking on "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.doubleClick(locator);
     }
     /**
@@ -186,7 +194,7 @@ class Steps {
      */
     async check(pageName, elementName) {
         log.interact('Checking "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.check(locator);
     }
     /**
@@ -196,7 +204,7 @@ class Steps {
      */
     async uncheck(pageName, elementName) {
         log.interact('Unchecking "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.uncheck(locator);
     }
     /**
@@ -206,7 +214,7 @@ class Steps {
      */
     async hover(pageName, elementName) {
         log.interact('Hovering over "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.hover(locator);
     }
     /**
@@ -216,7 +224,7 @@ class Steps {
      */
     async scrollIntoView(pageName, elementName) {
         log.interact('Scrolling "%s" in "%s" into view', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.scrollIntoView(locator);
     }
     /**
@@ -227,7 +235,7 @@ class Steps {
      */
     async fill(pageName, elementName, text) {
         log.interact('Filling "%s" in "%s" with text: "%s"', elementName, pageName, text);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.fill(locator, text);
     }
     /**
@@ -238,7 +246,7 @@ class Steps {
      */
     async uploadFile(pageName, elementName, filePath) {
         log.interact('Uploading file "%s" to "%s" in "%s"', filePath, elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.uploadFile(locator, filePath);
     }
     /**
@@ -252,7 +260,7 @@ class Steps {
      */
     async selectDropdown(pageName, elementName, options) {
         log.interact('Selecting dropdown option for "%s" in "%s" using options: %O', elementName, pageName, options ?? 'default (random)');
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         return await this.interact.selectDropdown(locator, options);
     }
     /**
@@ -264,7 +272,7 @@ class Steps {
      */
     async dragAndDrop(pageName, elementName, options) {
         log.interact('Dragging and dropping "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.dragAndDrop(locator, options);
     }
     /**
@@ -278,10 +286,10 @@ class Steps {
      */
     async dragAndDropListedElement(pageName, elementName, elementText, options) {
         log.interact('Dragging and dropping "%s" in "%s"', elementText, pageName);
-        const locator = await this.repo.getByText(this.page, pageName, elementName, elementText);
-        if (!locator)
+        const element = await this.repo.getByText(this.page, pageName, elementName, elementText);
+        if (!element)
             throw new Error(`No element with text "${elementText}" found for "${elementName}" in "${pageName}"`);
-        await this.interact.dragAndDrop(locator, options);
+        await this.interact.dragAndDrop(toLocator(element), options);
     }
     /**
      * Sets the value of a range/slider input element.
@@ -291,7 +299,7 @@ class Steps {
      */
     async setSliderValue(pageName, elementName, value) {
         log.interact('Setting slider "%s" in "%s" to value: %d', elementName, pageName, value);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.setSliderValue(locator, value);
     }
     /**
@@ -314,7 +322,7 @@ class Steps {
      */
     async getText(pageName, elementName) {
         log.extract('Getting text from "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         return await this.extract.getText(locator);
     }
     /**
@@ -326,7 +334,7 @@ class Steps {
      */
     async getAttribute(pageName, elementName, attributeName) {
         log.extract('Getting attribute "%s" from "%s" in "%s"', attributeName, elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         return await this.extract.getAttribute(locator, attributeName);
     }
     // ==========================================
@@ -339,7 +347,7 @@ class Steps {
      */
     async verifyPresence(pageName, elementName) {
         log.verify('Verifying presence of "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.verify.presence(locator);
     }
     /**
@@ -364,7 +372,7 @@ class Steps {
     async verifyText(pageName, elementName, expectedText, options) {
         const logDetail = options?.notEmpty ? 'is not empty' : `matches: "${expectedText}"`;
         log.verify('Verifying text of "%s" in "%s" %s', elementName, pageName, logDetail);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.verify.text(locator, expectedText, options);
     }
     /**
@@ -376,7 +384,7 @@ class Steps {
      */
     async verifyCount(pageName, elementName, options) {
         log.verify('Verifying count for "%s" in "%s" with options: %O', elementName, pageName, options);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.verify.count(locator, options);
     }
     /**
@@ -388,7 +396,7 @@ class Steps {
      */
     async verifyImages(pageName, elementName, scroll = true) {
         log.verify('Verifying images for "%s" in "%s" (scroll: %s)', elementName, pageName, scroll);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.verify.images(locator, scroll);
     }
     /**
@@ -399,7 +407,7 @@ class Steps {
      */
     async verifyTextContains(pageName, elementName, expectedText) {
         log.verify('Verifying "%s" in "%s" contains text: "%s"', elementName, pageName, expectedText);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.verify.textContains(locator, expectedText);
     }
     /**
@@ -424,7 +432,7 @@ class Steps {
      */
     async verifyAttribute(pageName, elementName, attributeName, expectedValue) {
         log.verify('Verifying "%s" in "%s" has attribute "%s" = "%s"', elementName, pageName, attributeName, expectedValue);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.verify.attribute(locator, attributeName, expectedValue);
     }
     /**
@@ -445,7 +453,7 @@ class Steps {
      */
     async verifyInputValue(pageName, elementName, expectedValue) {
         log.verify('Verifying input value of "%s" in "%s" matches: "%s"', elementName, pageName, expectedValue);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.verify.inputValue(locator, expectedValue);
     }
     /**
@@ -476,7 +484,7 @@ class Steps {
      */
     async clickListedElement(pageName, elementName, options) {
         log.interact('Clicking listed element in "%s" > "%s" with options: %O', pageName, elementName, options);
-        const baseLocator = await this.repo.get(this.page, pageName, elementName);
+        const baseLocator = toLocator(await this.repo.get(this.page, pageName, elementName));
         const target = await this.interact.getListedElement(baseLocator, options, this.repo);
         await this.interact.click(target);
     }
@@ -499,7 +507,7 @@ class Steps {
      */
     async verifyListedElement(pageName, elementName, options) {
         log.verify('Verifying listed element in "%s" > "%s" with options: %O', pageName, elementName, options);
-        const baseLocator = await this.repo.get(this.page, pageName, elementName);
+        const baseLocator = toLocator(await this.repo.get(this.page, pageName, elementName));
         const target = await this.interact.getListedElement(baseLocator, options, this.repo);
         if (options.expectedText !== undefined) {
             await this.verify.text(target, options.expectedText);
@@ -528,7 +536,7 @@ class Steps {
      */
     async getListedElementData(pageName, elementName, options) {
         log.extract('Extracting data from listed element in "%s" > "%s" with options: %O', pageName, elementName, options);
-        const baseLocator = await this.repo.get(this.page, pageName, elementName);
+        const baseLocator = toLocator(await this.repo.get(this.page, pageName, elementName));
         const target = await this.interact.getListedElement(baseLocator, options, this.repo);
         if (options.extractAttribute) {
             return await this.extract.getAttribute(target, options.extractAttribute);
@@ -547,7 +555,7 @@ class Steps {
      */
     async waitForState(pageName, elementName, state = 'visible') {
         log.wait('Waiting for "%s" in "%s" to be "%s"', elementName, pageName, state);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.utils.waitForState(locator, state);
     }
     /**
@@ -561,7 +569,7 @@ class Steps {
      */
     async typeSequentially(pageName, elementName, text, delay = 100) {
         log.interact('Typing "%s" sequentially into "%s" in "%s" (delay: %dms)', text, elementName, pageName, delay);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.typeSequentially(locator, text, delay);
     }
     // ==========================================
@@ -652,7 +660,7 @@ class Steps {
      */
     async clearInput(pageName, elementName) {
         log.interact('Clearing input "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.interact.clearInput(locator);
     }
     /**
@@ -664,7 +672,7 @@ class Steps {
      */
     async selectMultiple(pageName, elementName, values) {
         log.interact('Selecting multiple values on "%s" in "%s": %O', elementName, pageName, values);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         return await this.interact.selectMultiple(locator, values);
     }
     /**
@@ -677,7 +685,7 @@ class Steps {
      */
     async waitAndClick(pageName, elementName, state = 'visible') {
         log.interact('Waiting for "%s" in "%s" to be "%s", then clicking', elementName, pageName, state);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.utils.waitForState(locator, state);
         await this.interact.click(locator);
     }
@@ -692,10 +700,10 @@ class Steps {
      */
     async clickNth(pageName, elementName, index) {
         log.interact('Clicking element at index %d of "%s" in "%s"', index, elementName, pageName);
-        const locator = await this.repo.getByIndex(this.page, pageName, elementName, index);
-        if (!locator)
+        const element = await this.repo.getByIndex(this.page, pageName, elementName, index);
+        if (!element)
             throw new Error(`No element at index ${index} for "${elementName}" in "${pageName}"`);
-        await this.interact.click(locator);
+        await this.interact.click(toLocator(element));
     }
     // ==========================================
     // 📊 ADDITIONAL DATA EXTRACTION STEPS
@@ -721,7 +729,7 @@ class Steps {
      */
     async getAll(pageName, elementName, options) {
         log.extract('Extracting all from "%s" in "%s" with options: %O', elementName, pageName, options ?? 'text');
-        let locator = await this.repo.get(this.page, pageName, elementName);
+        let locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         if (options?.child) {
             if (typeof options.child === 'string') {
                 locator = locator.locator(options.child);
@@ -747,7 +755,7 @@ class Steps {
      */
     async getCount(pageName, elementName) {
         log.extract('Getting count of "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         return await this.extract.getCount(locator);
     }
     /**
@@ -759,7 +767,7 @@ class Steps {
      */
     async getInputValue(pageName, elementName) {
         log.extract('Getting input value of "%s" in "%s"', elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         return await this.extract.getInputValue(locator);
     }
     /**
@@ -771,7 +779,7 @@ class Steps {
      */
     async getCssProperty(pageName, elementName, property) {
         log.extract('Getting CSS "%s" from "%s" in "%s"', property, elementName, pageName);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         return await this.extract.getCssProperty(locator, property);
     }
     // ==========================================
@@ -787,7 +795,7 @@ class Steps {
      */
     async verifyOrder(pageName, elementName, expectedTexts) {
         log.verify('Verifying order of "%s" in "%s": %O', elementName, pageName, expectedTexts);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.verify.order(locator, expectedTexts);
     }
     /**
@@ -800,7 +808,7 @@ class Steps {
      */
     async verifyCssProperty(pageName, elementName, property, expectedValue) {
         log.verify('Verifying CSS "%s" of "%s" in "%s" = "%s"', property, elementName, pageName, expectedValue);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.verify.cssProperty(locator, property, expectedValue);
     }
     /**
@@ -812,7 +820,7 @@ class Steps {
      */
     async verifyListOrder(pageName, elementName, direction) {
         log.verify('Verifying "%s" in "%s" is sorted %s', elementName, pageName, direction);
-        const locator = await this.repo.get(this.page, pageName, elementName);
+        const locator = toLocator(await this.repo.get(this.page, pageName, elementName));
         await this.verify.listOrder(locator, direction);
     }
     // ==========================================
@@ -841,7 +849,7 @@ class Steps {
     async screenshot(pageNameOrOptions, elementName, options) {
         if (typeof pageNameOrOptions === 'string' && elementName) {
             log.extract('Taking screenshot of "%s" in "%s"', elementName, pageNameOrOptions);
-            const locator = await this.repo.get(this.page, pageNameOrOptions, elementName);
+            const locator = toLocator(await this.repo.get(this.page, pageNameOrOptions, elementName));
             return await this.extract.screenshot(locator, options);
         }
         const opts = typeof pageNameOrOptions === 'object' ? pageNameOrOptions : options;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitas-cerebrum/element-interactions",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A robust, readable interaction and assertion Facade for Playwright. Abstract away boilerplate into semantic, English-like methods, making your test automation framework cleaner, easier to maintain, and accessible to non-developers.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -55,8 +55,8 @@
   "license": "MIT",
   "dependencies": {
     "@civitas-cerebrum/context-store": "^0.0.2",
-    "@civitas-cerebrum/element-repository": "^0.0.6",
-    "@civitas-cerebrum/email-client": "^0.0.4",
+    "@civitas-cerebrum/element-repository": "^0.1.0",
+    "@civitas-cerebrum/email-client": "^0.0.5",
     "debug": "^4.4.3",
     "dotenv": "^17.3.1"
   }

package/skills/element-interactions.md

@@ -18,7 +18,7 @@ A two-package Playwright framework that decouples **element acquisition** (`@civ
 These rules are non-negotiable. They override helpfulness, initiative, and assumptions. If you are unsure about any rule, ask the user. Do not guess.
 
 ### 1. Do NOT skip stages
-- This skill operates in three stages. You MUST complete each stage and get user approval before advancing.
+- This skill operates in four stages. You MUST complete each stage and get user approval before advancing.
 - Do NOT jump ahead. Do NOT write automation code during the discovery stage.
 - Exception: API questions and fix/edit requests bypass the staged flow (see Opening section).
 
@@ -57,10 +57,10 @@ These rules are non-negotiable. They override helpfulness, initiative, and assum
 
 ## Staged Workflow
 
-This skill operates in **three stages**. Each stage has a hard gate — you MUST get user approval before advancing to the next stage.
+This skill operates in **four stages**. Each stage has a hard gate — you MUST get user approval before advancing to the next stage.
 
 <HARD-GATE>
-Do NOT write any automation code until Stage 3. Do NOT create selectors until Stage 2. Do NOT skip the discovery conversation in Stage 1. Every engagement follows all three stages regardless of perceived simplicity.
+Do NOT write any automation code until Stage 3. Do NOT create selectors until Stage 2. Do NOT skip the discovery conversation in Stage 1. Every engagement follows all four stages regardless of perceived simplicity.
 </HARD-GATE>
 
 ### Checklist
@@ -74,7 +74,9 @@ You MUST create a task for each of these items and complete them in order:
 5. **User approves selectors** — hard gate
 6. **Stage 3: Write Automation** — write the test using the Steps API and approved selectors
 7. **Run and validate** — execute the test, inspect failures visually, iterate
-8. **Commit** — commit after confirmed success
+8. **Stage 4: API Compliance Review** — review all scenarios against the API Reference to catch incorrect usage
+9. **Fix any issues found** — correct API misuse, re-run tests
+10. **Commit** — commit after confirmed success
 
 ### Process Flow
 
@@ -114,6 +116,12 @@ digraph element_interactions {
     "New selector needed?" [shape=diamond];
     "Mini-inspection:\ninspect DOM, propose,\nget approval" [shape=box];
     "Inspect screenshot, fix, re-run" [shape=box];
+
+    "STAGE 4: API Compliance Review" [shape=box, style=bold];
+    "Review all test code\nagainst API Reference" [shape=box];
+    "Issues found?" [shape=diamond];
+    "Fix API misuse,\nre-run tests" [shape=box];
+    "All scenarios pass\nafter fixes?" [shape=diamond];
     "Commit" [shape=doublecircle];
 
     "Skill activated" -> "Read user message";
@@ -153,12 +161,20 @@ digraph element_interactions {
     "STAGE 3: Write Automation" -> "Write test using Steps API";
     "Write test using Steps API" -> "Run test";
     "Run test" -> "Test passes?";
-    "Test passes?" -> "Commit" [label="yes"];
+    "Test passes?" -> "STAGE 4: API Compliance Review" [label="yes"];
     "Test passes?" -> "New selector needed?" [label="no"];
     "New selector needed?" -> "Mini-inspection:\ninspect DOM, propose,\nget approval" [label="yes"];
     "New selector needed?" -> "Inspect screenshot, fix, re-run" [label="no — code issue"];
     "Mini-inspection:\ninspect DOM, propose,\nget approval" -> "Inspect screenshot, fix, re-run";
     "Inspect screenshot, fix, re-run" -> "Run test";
+
+    "STAGE 4: API Compliance Review" -> "Review all test code\nagainst API Reference";
+    "Review all test code\nagainst API Reference" -> "Issues found?";
+    "Issues found?" -> "Commit" [label="no — all correct"];
+    "Issues found?" -> "Fix API misuse,\nre-run tests" [label="yes"];
+    "Fix API misuse,\nre-run tests" -> "All scenarios pass\nafter fixes?";
+    "All scenarios pass\nafter fixes?" -> "Commit" [label="yes"];
+    "All scenarios pass\nafter fixes?" -> "Inspect screenshot, fix, re-run" [label="no — regression"];
 }
 ```
 
@@ -284,7 +300,7 @@ Show the user the exact JSON entries you want to add:
 
 ### Writing Process
 
-1. **Check project setup.** Read `tests/fixtures/base.ts` and `playwright.config.ts` — create or update only if missing or broken.
+1. **Check project setup.** Read `tests/fixtures/base.ts` and `playwright.config.ts` — create or update only if missing or broken. Also verify that `.gitignore` includes `.claude/` and `CLAUDE.md` to prevent Claude Code configuration from being pushed to the repository — add them if missing.
 2. **Add approved selectors** to `page-repository.json` (if not already done).
 3. **Write the test file** using the Steps API. Every interaction goes through `steps.*` methods — no raw `page.locator()` calls.
 4. **Run the test** with `npx playwright test <test-file>`.
@@ -297,6 +313,59 @@ When the user asks to fix or edit an existing test, skip Stages 1 and 2. Read th
 
 ---
 
+## Stage 4: API Compliance Review
+
+**Goal:** After all scenarios pass, review every test file written in this session against the API Reference to ensure correct usage of the `@civitas-cerebrum/element-interactions` package.
+
+**This stage triggers automatically** once all tests pass in Stage 3. Do NOT skip it — even if the tests pass, they may be using the API incorrectly (wrong argument order, deprecated methods, missing options, incorrect types).
+
+### Review Checklist
+
+For each test file, verify:
+
+1. **Method signatures** — every `steps.*` call matches the exact signature in the API Reference (correct argument count, correct argument order, correct types).
+2. **Imports** — all types used (`DropdownSelectType`, `EmailFilterType`, `FillFormValue`, etc.) are imported from `@civitas-cerebrum/element-interactions` (or `@civitas-cerebrum/email-client` for email types). No invented imports.
+3. **Page/element naming** — `pageName` uses PascalCase, `elementName` uses camelCase, and both match entries in `page-repository.json`.
+4. **Listed element options** — `child` uses `{ pageName, elementName }` repo references where possible instead of inline selectors (per Rule 5).
+5. **Dropdown select usage** — `DropdownSelectType.RANDOM`, `.VALUE`, or `.INDEX` with the correct companion field (`value` or `index`).
+6. **Email API usage** — `steps.sendEmail` / `steps.receiveEmail` / `steps.receiveAllEmails` / `steps.cleanEmails` match the documented signatures. Filter types use `EmailFilterType` enum.
+7. **No raw Playwright calls** — no `page.locator()`, `page.click()`, `page.fill()`, or other raw Playwright methods where a `steps.*` equivalent exists.
+8. **Fixture usage** — the test destructures only fixtures provided by `baseFixture` (`steps`, `repo`, `interactions`, `contextStore`, `page`) plus any custom fixtures defined in the project's `base.ts`.
+9. **Waiting methods** — correct state strings (`'visible'`, `'hidden'`, `'attached'`, `'detached'`) and correct usage of `waitForResponse` callback pattern.
+10. **Verification methods** — correct option shapes (`{ exactly }`, `{ greaterThan }`, `{ lessThan }` for `verifyCount`; `{ notEmpty: true }` for `verifyText`).
+
+### Process
+
+1. **Read each test file** written or modified in this session.
+2. **Cross-reference every API call** against the API Reference section below.
+3. **Report findings** to the user — list any issues found with the specific line, what's wrong, and the correct usage.
+4. **If issues are found:** investigate *why* the non-compliant code was written — was the API misunderstood? Was a method signature wrong in the scenario? Did a previous stage produce incorrect assumptions? Understanding the root cause prevents the same mistake from recurring in the next scenario. Then fix, re-run the tests, and confirm they still pass.
+5. **If fixes cause a test failure:** follow Rule 6 — inspect the failure screenshot first before attempting any further fix. Do NOT guess from the error message alone.
+6. **If no issues are found:** confirm compliance and proceed to commit.
+
+### Output Format
+
+Present the review as:
+
+> **API Compliance Review**
+>
+> Reviewed: `tests/example.spec.ts`, `tests/login.spec.ts`
+>
+> - **`example.spec.ts:15`** — `steps.backOrForward('back')` should be `steps.backOrForward('BACKWARDS')` (uses uppercase enum-style strings)
+> - **`login.spec.ts:8`** — missing import for `DropdownSelectType`
+>
+> [number] issue(s) found. Fixing now.
+
+Or if clean:
+
+> **API Compliance Review**
+>
+> Reviewed: `tests/example.spec.ts`
+>
+> All API calls match the documented signatures. No issues found.
+
+---
+
 ## API Reference
 
 The following sections document the full API available for writing tests in Stage 3.
@@ -358,7 +427,7 @@ Every method takes `pageName` and `elementName` as its first two arguments, matc
 
 **Imports** — add at the top of your test file as needed:
 ```ts
-import { DropdownSelectType, ListedElementMatch, VerifyListedOptions, GetListedDataOptions, FillFormValue, ScreenshotOptions } from '@civitas-cerebrum/element-interactions';
+import { DropdownSelectType, ListedElementMatch, VerifyListedOptions, GetListedDataOptions, FillFormValue, ScreenshotOptions, EmailFilterType, EmailMarkAction, WebElement } from '@civitas-cerebrum/element-interactions';
 ```
 
 #### Navigation
@@ -404,10 +473,10 @@ const val2 = await steps.selectDropdown('PageName', 'elementName', { type: Dropd
 const val3 = await steps.selectDropdown('PageName', 'elementName', { type: DropdownSelectType.INDEX, index: 2 });
 await steps.selectMultiple('PageName', 'multiSelect', ['opt1', 'opt2']);
 
-// Drag and drop
-await steps.dragAndDrop('PageName', 'elementName', { target: otherLocator });
+// Drag and drop — target accepts a Locator or Element from the repository
+await steps.dragAndDrop('PageName', 'elementName', { target: otherLocatorOrElement });
 await steps.dragAndDrop('PageName', 'elementName', { xOffset: 100, yOffset: 0 });
-await steps.dragAndDropListedElement('PageName', 'elementName', 'Item Label', { target: otherLocator });
+await steps.dragAndDropListedElement('PageName', 'elementName', 'Item Label', { target: otherLocatorOrElement });
 ```
 
 #### Data Extraction
@@ -511,27 +580,34 @@ const buf3 = await steps.screenshot('PageName', 'elementName');             // e
 
 ### Accessing the Repository Directly
 
-Use `repo` when you need to filter by visible text, iterate all matches, or pick a random item:
+Use `repo` when you need to filter by visible text, iterate all matches, or pick a random item. Repository methods return `Element` wrappers (not raw Playwright `Locator` objects). The `Element` interface provides common methods like `click()`, `fill()`, `textContent()`, etc. To access the underlying Playwright `Locator` (e.g. for Playwright-specific assertions), cast to `WebElement`:
 
 ```ts
+import { WebElement } from '@civitas-cerebrum/element-interactions';
+
 test('example', async ({ page, repo, steps }) => {
   await steps.navigateTo('/');
   const link = await repo.getByText(page, 'HomePage', 'categories', 'Forms');
-  await link?.click();
+  await link?.click();                              // Element.click() works directly
+
+  // When you need the underlying Locator:
+  const element = await repo.get(page, 'PageName', 'elementName');
+  const locator = (element as WebElement).locator;  // access raw Playwright Locator
 });
 ```
 
 ```ts
-await repo.get(page, 'PageName', 'elementName');
-await repo.getAll(page, 'PageName', 'elementName');
-await repo.getRandom(page, 'PageName', 'elementName');
-await repo.getByText(page, 'PageName', 'elementName', 'Text');
+await repo.get(page, 'PageName', 'elementName');               // single Element
+await repo.getAll(page, 'PageName', 'elementName');             // array of Elements
+await repo.getRandom(page, 'PageName', 'elementName');          // random from matches
+await repo.getByText(page, 'PageName', 'elementName', 'Text'); // exact match, then contains fallback
 await repo.getByAttribute(page, 'PageName', 'elementName', 'data-status', 'active');
 await repo.getByAttribute(page, 'PageName', 'elementName', 'href', '/path', { exact: false });
 await repo.getByIndex(page, 'PageName', 'elementName', 2);
 await repo.getByRole(page, 'PageName', 'elementName', 'button');
 await repo.getVisible(page, 'PageName', 'elementName');
 repo.getSelector('PageName', 'elementName');        // sync, returns raw selector string
+repo.getSelectorRaw('PageName', 'elementName');     // sync, returns { strategy, value }
 repo.setDefaultTimeout(10000);
 ```
 
@@ -556,7 +632,25 @@ Send and receive emails in tests. Supports plain-text, inline HTML, and HTML fil
 
 #### Setup
 
+Pass email credentials using the split config (recommended) or the legacy combined format. You can provide `smtp` only, `imap` only, or both:
+
 ```ts
+// Split config (recommended)
+export const test = baseFixture(base, 'tests/data/page-repository.json', {
+  emailCredentials: {
+    smtp: {
+      email: process.env.SENDER_EMAIL!,
+      password: process.env.SENDER_PASSWORD!,
+      host: process.env.SENDER_SMTP_HOST!,
+    },
+    imap: {
+      email: process.env.RECEIVER_EMAIL!,
+      password: process.env.RECEIVER_PASSWORD!,
+    },
+  }
+});
+
+// Legacy combined format (still supported)
 export const test = baseFixture(base, 'tests/data/page-repository.json', {
   emailCredentials: {
     senderEmail: process.env.SENDER_EMAIL!,
@@ -572,6 +666,7 @@ export const test = baseFixture(base, 'tests/data/page-repository.json', {
 
 ```ts
 await steps.sendEmail({ to: 'user@example.com', subject: 'Test', text: 'Hello' });
+await steps.sendEmail({ to: 'user@example.com', subject: 'Report', html: '<h1>Results</h1>' });
 await steps.sendEmail({ to: 'user@example.com', subject: 'Report', htmlFile: 'emails/report.html' });
 ```
 
@@ -598,6 +693,25 @@ const allEmails = await steps.receiveAllEmails({
 });
 ```
 
+#### Marking Emails
+
+```ts
+import { EmailMarkAction } from '@civitas-cerebrum/element-interactions';
+
+await steps.markEmail(EmailMarkAction.READ, {
+  filters: [{ type: EmailFilterType.SUBJECT, value: 'OTP' }]
+});
+await steps.markEmail(EmailMarkAction.FLAGGED, {
+  filters: [{ type: EmailFilterType.FROM, value: 'noreply@example.com' }]
+});
+await steps.markEmail(EmailMarkAction.ARCHIVED, {
+  filters: [{ type: EmailFilterType.SUBJECT, value: 'Report' }]
+});
+await steps.markEmail(EmailMarkAction.UNREAD); // mark all in folder
+```
+
+Mark actions: `READ`, `UNREAD`, `FLAGGED`, `UNFLAGGED`, `ARCHIVED`.
+
 #### Cleaning the Inbox
 
 ```ts