@molecule/app-e2e-playwright 1.0.0 → 1.0.1

package/README.md

@@ -1,26 +1,146 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-09-12T19:49:04.133Z
+-->
+
 # @molecule/app-e2e-playwright
 
-Real Playwright browsers for the e2e bond — the user's machine and CI
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+E2E bond that opens real Playwright browsers. Inside a molecule sandbox the
+same specs drive the live preview through `@molecule/app-e2e-preview`; on
+your own machine and in CI this bond gives them Chromium, Firefox or WebKit
+with everything Playwright offers — screenshots, traces, videos, network
+interception.
+
+When the test runner picks the `playwright` provider, `@molecule/app-e2e`'s
+`test` IS Playwright's `test`, so this bond is only reached by scripts that
+call `connect()` themselves (a measurement script, a smoke check outside the
+runner). Under `npx playwright test`, Playwright's own fixtures launch the
+browser as usual.
+
+## Quick Start
+
+```ts
+// e2e/bonds.ts (scaffolded)
+import { resolveE2EProviderName, setProvider } from '@molecule/app-e2e'
+import { provider as playwright } from '@molecule/app-e2e-playwright'
+import { provider as preview } from '@molecule/app-e2e-preview'
+
+setProvider(resolveE2EProviderName() === 'preview' ? preview : playwright)
+
+// a script
+import { connectPlaywright } from '@molecule/app-e2e-playwright'
+const page = await connectPlaywright({
+  baseURL: 'http://localhost:3000',
+  viewport: { width: 390, height: 844 },
+})
+await page.goto('/')
+await page.screenshot({ path: 'home-phone.png' })
+await page.close() // closes the context and the browser too
+```
 
 ## Type
 
 `provider`
 
-## Implements
+## Installation
+
+```bash
+npm install @molecule/app-e2e-playwright @molecule/app-bond @molecule/app-e2e @playwright/test
+```
+
+## API
+
+### Interfaces
+
+#### `PlaywrightConnectOptions`
+
+Options for `provider.connect()` beyond the core's.
+
+```typescript
+interface PlaywrightConnectOptions extends E2EConnectOptions {
+  /** Browser to launch; default `chromium` (also `MOL_E2E_BROWSER`). */
+  browser?: PlaywrightBrowserName
+  /** Show the browser window; default headless (also `MOL_E2E_HEADED=1`). */
+  headed?: boolean
+  /** Extra launch options passed through to Playwright. */
+  launchOptions?: LaunchOptions
+}
+```
+
+### Types
+
+#### `PlaywrightBrowserName`
+
+Which Playwright browser to launch.
+
+```typescript
+type PlaywrightBrowserName = 'chromium' | 'firefox' | 'webkit'
+```
+
+### Functions
+
+#### `connectPlaywright(options?)`
+
+Open a real browser page from any script.
+
+```typescript
+function connectPlaywright(options?: PlaywrightConnectOptions): Promise<Page>
+```
+
+### Constants
+
+#### `provider`
+
+The bond: `setProvider(provider)` in your `e2e/bonds.ts`.
+
+```typescript
+const provider: E2EProvider
+```
+
+## Core Interface
+
+Implements `@molecule/app-e2e` interface.
+
+## Bond Wiring
+
+Setup function to register this provider with the core interface:
+
+```typescript
+import { setProvider } from '@molecule/app-e2e'
+import { provider } from '@molecule/app-e2e-playwright'
 
-`@molecule/app-e2e`
+export function setupE2ePlaywright(): void {
+  setProvider(provider)
+}
+```
 
 ## Injection Notes
 
 ### Requirements
 
-- None
+Peer dependencies:
 
-### Post-Injection Steps
+- `@molecule/app-bond` ^1.0.1
+- `@molecule/app-e2e` ^1.0.0
+- `@playwright/test` ^1.40.0
 
-- Run `npm install` to install dependencies
-- Run `npm run build` to compile
+### Runtime Dependencies
 
-### Known Limitations
+- `@molecule/app-bond`
+- `@molecule/app-e2e`
+- `@playwright/test`
 
-- None yet
+- Browsers are installed once with `npx playwright install chromium`
+  (`@playwright/test` never downloads them on `npm install`). The launch
+  error says so when they are missing.
+- `MOL_E2E_BROWSER=firefox|webkit` picks the engine; `MOL_E2E_HEADED=1`
+  shows the window.
+- Do not use this bond inside a molecule sandbox: there is no browser there
+  by design, and the preview bond is the one that works.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-e2e-playwright",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "E2E bond that opens real Playwright browsers — the same specs that drive the live preview inside a molecule sandbox run here on your machine and in CI, with screenshots, traces and network interception.",
   "type": "module",
   "main": "dist/index.js",
@@ -32,7 +32,7 @@
     "url": "https://github.com/molecule-dev/molecule.git",
     "directory": "packages/app/bonds/e2e/playwright"
   },
-  "homepage": "https://molecule.dev",
+  "homepage": "https://www.molecule.dev/packages/app-e2e-playwright",
   "bugs": {
     "url": "https://github.com/molecule-dev/molecule/issues"
   },
@@ -45,8 +45,8 @@
     "@playwright/test": "^1.40.0"
   },
   "devDependencies": {
-    "@molecule/app-bond": "1.0.1",
-    "@molecule/app-e2e": "1.0.0",
+    "@molecule/app-bond": "1.0.2",
+    "@molecule/app-e2e": "1.0.1",
     "@playwright/test": "1.62.0",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",