Rewrite the README and document driver support

README.md

@@ -8,79 +8,97 @@
 
 </div>
 
-# Playwright PHP - Mink Driver
+# Playwright PHP Mink Driver
 
-A [Mink](https://mink.behat.org/) driver powered by **[Playwright PHP](https://github.com/playwright-php)**.
+A [Mink](https://mink.behat.org/) driver powered by
+[Playwright PHP](https://github.com/playwright-php/playwright).
 
-
-> [!IMPORTANT]  
-> This package is **experimental**. Its API may still change before the upcoming `1.0` release.  
->  
-> Curious or interested? Try it out, [share your feedback](https://github.com/playwright-php/playwright-mink/issues), or ideas!
-
-
-## Features
-
-- Run real browsers: Chromium, Firefox, WebKit (headless or not)  
-- Control the DOM: navigation, forms, cookies, JS, events  
-- Handle windows, iframes, uploads, screenshots, dialogs
+Use it to keep an existing Mink test suite while running its browser interactions
+in Chromium, Firefox, or WebKit through Playwright.
 
 ## Installation
 
-**Requirements**
-
-- PHP 8.2 or higher
-- [Playwright PHP](https://github.com/playwright-php/playwright)
-
-**Install the driver**
+The driver requires PHP 8.2 or later, Mink 1.10 or later, and Playwright PHP 1.x.
 
 ```bash
 composer require --dev playwright-php/playwright-mink
+vendor/bin/playwright-install --browsers
 ```
 
 ## Usage
 
+Create the driver, pass it to a Mink session, and use the regular Mink API:
+
 ```php
+<?php
+
 use Behat\Mink\Session;
 use Playwright\Mink\Driver\PlaywrightDriver;
 
-$driver = new PlaywrightDriver(browserType: 'chromium', headless: true);
-$session = new Session($driver);
+$driver = new PlaywrightDriver(
+    browserType: 'chromium',
+    headless: true,
+);
 
+$session = new Session($driver);
 $session->start();
-$session->visit('https://example.org');
 
-echo $session->getPage()->getText();
+try {
+    $session->visit('https://example.com');
 
-$session->stop();
+    echo $session->getPage()->getText();
+} finally {
+    $session->stop();
+}
 ```
 
-## Testing
+The constructor accepts:
 
-This driver is validated against the official [`minkphp/driver-testsuite`](https://github.com/minkphp/driver-testsuite).
+- `browserType`: `chromium`, `firefox`, or `webkit`;
+- `headless`: whether to run without a visible browser window;
+- `launchOptions`: browser launch options such as `slowMo` and `args`;
+- `contextOptions`: options passed to the Playwright browser context.
 
-**Test Results**: 212/218 tests passing (97.2%) with 491 assertions
+```php
+$driver = new PlaywrightDriver(
+    browserType: 'firefox',
+    headless: false,
+    launchOptions: [
+        'slowMo' => 100,
+    ],
+    contextOptions: [
+        'viewport' => ['width' => 1440, 'height' => 900],
+        'locale' => 'en-US',
+    ],
+);
+```
 
-**Start the test server**
+See [Driver support](docs/driver-support.md) for the tested Mink surface and
+known limitations.
+
+## Testing
+
+The driver is tested against the official
+[`minkphp/driver-testsuite`](https://github.com/minkphp/driver-testsuite).
+
+Install dependencies, start its test server, then run PHPUnit:
 
 ```bash
+composer install
+vendor/bin/playwright-install --browsers
 vendor/bin/mink-test-server
 ```
 
-**Run tests**
+In another terminal:
 
 ```bash
 vendor/bin/phpunit
 ```
 
-### Known Limitations
-
-6 tests are skipped due to known limitations:
-
-- **jQuery UI Drag & Drop** (2 tests): jQuery UI uses mouse events API, Playwright uses HTML5 Drag & Drop API - these are incompatible
-- **Popup Window Tracking** (4 tests): Async event timing with `window.open()` requires improvements in Playwright PHP event handling
+The test suite currently excludes scenarios that depend on jQuery UI drag and
+drop or asynchronous popup discovery. These limitations are documented in
+[Driver support](docs/driver-support.md).
 
 ## License
 
-This package is released by the [Playwright PHP](https://playwright-php.dev) 
-project under the MIT License. See the [LICENSE](LICENSE) file for details.
+Playwright PHP Mink Driver is released under the [MIT License](LICENSE).

docs/driver-support.md

@@ -0,0 +1,52 @@
+# Driver support
+
+Playwright PHP Mink Driver implements Mink's browser-facing driver API on top of
+Playwright PHP. Existing test code continues to use Mink sessions, pages, and
+nodes; the driver translates those operations to Playwright.
+
+## Supported workflows
+
+The driver covers the regular Mink workflows exercised by the official driver
+test suite:
+
+- navigation and page content;
+- form fields, buttons, links, and selections;
+- cookies and request headers;
+- JavaScript evaluation;
+- screenshots and file uploads;
+- frames and browser windows;
+- keyboard and mouse interactions.
+
+Support is verified by `minkphp/driver-testsuite`, rather than by a separate list
+of methods maintained by hand.
+
+## Known limitations
+
+### jQuery UI drag and drop
+
+The upstream driver test suite contains drag-and-drop scenarios implemented
+with jQuery UI's mouse-event model. Playwright's high-level drag-and-drop
+operation follows the browser's HTML drag-and-drop model, so those scenarios
+are currently excluded.
+
+### Popup discovery
+
+Scenarios that open and immediately inspect a new window are currently
+excluded. Popup registration is asynchronous in Playwright PHP, while Mink's
+window API expects the new window to be discoverable synchronously.
+
+## Browser coverage
+
+The driver accepts `chromium`, `firefox`, and `webkit`. The repository CI
+currently runs the official driver test suite with Chromium on PHP 8.3 and 8.4.
+Firefox, WebKit, and PHP 8.2 are supported by the package constraints but are
+not part of the active CI matrix.
+
+## Reporting a compatibility issue
+
+When reporting a driver mismatch, include:
+
+- the smallest Mink operation that reproduces it;
+- the browser and PHP versions;
+- the versions of Mink, Playwright PHP, and this driver;
+- whether the same interaction succeeds through Playwright PHP directly.