v1.1.0: pooled runtime, 959 tests, production hardening (0 squash)

2025-08-15 10:00:00 -07:00
commit 92deb689cd
321 changed files with 79170 additions and 0 deletions
@@ -0,0 +1,36 @@
+# Security Policy — imhotep-playwright
+
+## Fresh Context Per Run
+
+Each `imhotep(page)` call creates a fresh execution context:
+
+- **Deterministic mode**: Seeded LCG + monotonic counter IDs + stable clock. No shared state between runs.
+- **Volatile mode**: UUID/nanoid + Date.now + Math.random. Fresh for each invocation.
+- **No persistent state**: Execution contexts are not stored or reused across test files unless explicitly passed by the user.
+
+## CDP Direct Connection
+
+Imhotep-playwright uses **two** browser communication paths:
+
+1. **Fast path**: `page.evaluate()` for simple geometry extraction (bounding boxes only).
+2. **Full path**: Direct Chrome DevTools Protocol (CDP) session for deep extraction (styles, topology, transforms, fragments) via `imhotep-cdp` package.
+
+The CDP path creates a direct debugging session with full DOM/CSS/Runtime access. This is a privileged channel. The Playwright package imports `CDPExtractor`, `createSessionManager`, and `resolveSelector` directly from `imhotep-cdp`.
+
+Trust boundary: CDP sessions are created within the local Playwright browser context. No remote debugger dialing occurs.
+
+## Trusted vs Untrusted Renderer Distinction
+
+Imhotep distinguishes between trusted and untrusted renderers:
+
+- **Trusted renderers**: Built-in React, Vue, and Storybook adapters that ship with Imhotep. These execute known mount/unmount code.
+- **Untrusted renderers**: User-provided custom adapters. These run arbitrary user code in the Node.js process. Treat custom adapters with the same caution as any dependency.
+- **Renderer isolation**: Each property run creates a fresh mount container. Renderers do not persist between runs unless the test author explicitly caches them.
+
+## Playwright Peer Dependency
+
+Imhotep-playwright requires Playwright as a peer dependency. Ensure your Playwright version is kept up to date to receive the latest browser security patches.
+
+```bash
+npm install --save-dev @playwright/test@latest playwright@latest
+```