@letsrunit/playwright 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# Playwright Package (`@letsrunit/playwright`)
+
+## Installation
+
+```bash
+npm install @letsrunit/playwright
+# or
+yarn add @letsrunit/playwright
+```
+
+Low-level Playwright utilities and enhancements for `@letsrunit`. This package provides a robust set of tools for interacting with and extracting information from web pages, optimized for AI-driven automation.
+
+## Exported Utilities
+
+### Element Discovery & Interaction
+
+- **`smartLocator(page, selector)`**: An enhanced locator that supports both standard CSS/XPath and higher-level semantic selectors.
+- **`findField(page, label)`**: Finds form fields based on their associated labels or placeholders.
+- **`scrollIntoView(locator)`**: Ensures an element is visible before interaction.
+
+### Page Analysis
+
+- **`extractPageInfo(page)`**: A comprehensive helper that extracts the title, URL, metadata, and captures a screenshot of the page.
+- **`detectLanguage(page)`**: Detects the primary language of the page content.
+- **`snapshot(page)`**: Captures a cleaned-up and formatted HTML snapshot of the current page, optimized for LLM consumption.
+
+### Wait Helpers
+
+- **`waitForIdle(page)`**: Waits for the page to reach a network-idle and stability state.
+- **`waitForText(page, text)`**: Waits for specific text to appear on the page.
+
+### DOM & HTML Utilities
+
+- **`formatHtml(html)`**: Prettifies and cleans up HTML strings.
+- **`scrubHtml(html)`**: Removes noisy elements (scripts, styles, etc.) from HTML to reduce token usage for AI.
+- **`unifiedHtmlDiff(oldHtml, newHtml)`**: Calculates a meaningful diff between two HTML states.
+
+## Testing
+
+Run tests for this package:
+
+```bash
+yarn test
+```

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+import { Browser, BrowserContextOptions, Page, Locator, PageScreenshotOptions } from '@playwright/test';
+import { Scalar, Range } from '@letsrunit/utils';
+
+declare function browse(browser: Browser, options?: BrowserContextOptions): Promise<Page>;
+
+interface SetOptions {
+    force?: boolean;
+    noWaitAfter?: boolean;
+    timeout?: number;
+}
+type Value = Scalar | Scalar[] | Range | boolean | null;
+
+declare function setFieldValue(el: Locator, value: Value, options?: SetOptions): Promise<void>;
+
+declare function formatHtml(page: string | Page): Promise<string>;
+
+/**
+ * Locates an element using Playwright selectors, with fallbacks.
+ */
+declare function locator(page: Page, selector: string): Promise<Locator>;
+
+declare const createDateEngine: () => {
+    query(root: Element | Document, body: string): Element | null;
+    queryAll(root: Element | Document, body: string): Element[];
+    _parseSelector(body: string): Date | null;
+    _matchesDate(el: Element, targetDate: Date, locale: string, body: string): {
+        matched: boolean;
+        type: "full" | "partial";
+    };
+};
+
+declare const createFieldEngine: () => {
+    _compileMatcher(body: string): (s: string | null | undefined) => boolean;
+    query(root: Element | Document, body: string): Element | null;
+    queryAll(root: Element | Document, body: string): Element[];
+};
+
+interface Snapshot {
+    url: string;
+    html: string;
+    screenshot: File;
+}
+interface PageInfo {
+    /** Page name (from <title> or meta tags) */
+    name?: string;
+    /** Short page description (meta description or OG/Twitter) */
+    description?: string;
+    /** Main image for previews (OpenGraph/Twitter) */
+    image?: string;
+    /** Site or brand logo if available */
+    logo?: string;
+    /** Author name if specified */
+    author?: string;
+    /** Publisher or organization name */
+    publisher?: string;
+    /** Page language, e.g. "en", "nl-NL" */
+    lang?: string;
+    /** Favicon URL */
+    favicon?: string;
+    /** Canonical or resolved page URL */
+    url: string;
+    /** Screenshot of the page */
+    screenshot?: File;
+}
+
+declare function snapshot(page: Page): Promise<Snapshot>;
+
+declare function screenshot(page: Page, options?: PageScreenshotOptions): Promise<File>;
+
+declare function scrollToCenter(locator: Locator): Promise<void>;
+
+type Options = {
+    timeoutMs?: number;
+    preferReject?: boolean;
+    lang?: string;
+    pollIntervalMs?: number;
+    settleAfterActionMs?: number;
+    quietPeriodMs?: number;
+    minSweepMs?: number;
+    maxActions?: number;
+    verbose?: boolean;
+};
+declare function suppressInterferences(page: Page, opts?: Options): Promise<void>;
+
+declare function formatDateForInput(date: Date, type: string | null): string;
+declare function formatDate(d: Date, format: string): string;
+declare function getMonthNames(locale?: string): string[];
+
+declare function waitForIdle(page: Page, timeout?: number): Promise<void>;
+declare function waitForMeta(page: Page, timeout?: number): Promise<void>;
+/** Wait until the DOM hasn't changed for `quiet` (default 500ms). */
+declare function waitForDomIdle(page: Page, { quiet, timeout }?: {
+    quiet?: number;
+    timeout?: number;
+}): Promise<void>;
+declare function waitForAnimationsToFinish(root: Locator): Promise<void>;
+declare function waitForUrlChange(page: Page, prevUrl: string, timeout: number): Promise<boolean>;
+declare function waitUntilEnabled(page: Page, target: Locator, timeout: number): Promise<void>;
+declare function waitAfterInteraction(page: Page, target: Locator, opts?: {
+    prevUrl?: string;
+    navTimeout?: number;
+    settleTimeout?: number;
+    quietMs?: number;
+}): Promise<void>;
+
+export { type PageInfo, type Snapshot, browse, createDateEngine, createFieldEngine, formatDate, formatDateForInput, formatHtml, getMonthNames, locator, screenshot, scrollToCenter, setFieldValue, snapshot, suppressInterferences, waitAfterInteraction, waitForAnimationsToFinish, waitForDomIdle, waitForIdle, waitForMeta, waitForUrlChange, waitUntilEnabled };