npm - @minhduydev/mdpi - Versions diffs - 0.3.0 - Mend

@minhduydev/mdpi 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (561) hide show

package/dist/template/.pi/skills/performance-optimization/references/performance-checklist.md ADDED Viewed

@@ -0,0 +1,85 @@
+# Performance Checklist
+Quick reference for web application performance. Use alongside the `performance-optimization` skill.
+## Core Web Vitals Targets
+| Metric | Good | Needs Work | Poor |
+|--------|------|------------|------|
+| LCP (Largest Contentful Paint) | ≤ 2.5s | ≤ 4.0s | > 4.0s |
+| INP (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms | > 500ms |
+| CLS (Cumulative Layout Shift) | ≤ 0.1 | ≤ 0.25 | > 0.25 |
+## Frontend Checklist
+### Images
+- [ ] Modern formats (WebP, AVIF)
+- [ ] Responsively sized (`srcset` and `sizes`)
+- [ ] Explicit `width` and `height` (prevents CLS)
+- [ ] Below-the-fold images: `loading="lazy"`, `decoding="async"`
+- [ ] Hero/LCP images: `fetchpriority="high"`, no lazy loading
+### JavaScript
+- [ ] Bundle size under 200KB gzipped (initial load)
+- [ ] Code splitting with dynamic `import()`
+- [ ] Tree shaking enabled
+- [ ] No blocking JavaScript in `<head>` (use `defer` or `async`)
+- [ ] Heavy computation offloaded to Web Workers
+- [ ] Long tasks (> 50ms) broken up (`scheduler.yield()`, `requestIdleCallback`)
+### CSS
+- [ ] Critical CSS inlined or preloaded
+- [ ] No render-blocking CSS for non-critical styles
+- [ ] No CSS-in-JS runtime cost in production (use extraction)
+### Fonts
+- [ ] Limited to 2–3 font families, 2–3 weights each
+- [ ] WOFF2 format only
+- [ ] Self-hosted when possible
+- [ ] `font-display: swap` (or `optional` for non-critical)
+- [ ] Subsetted via `unicode-range`
+- [ ] System font stack considered before any custom font
+### Network
+- [ ] Static assets cached with long `max-age` + content hashing
+- [ ] API responses cached where appropriate
+- [ ] HTTP/2 or HTTP/3 enabled
+- [ ] Resources preconnected for known origins
+- [ ] `fetchpriority` used on critical resources
+## Backend Checklist
+- [ ] Database queries have appropriate indexes
+- [ ] N+1 queries eliminated
+- [ ] Expensive operations cached (Redis, in-memory)
+- [ ] Pagination on list endpoints
+- [ ] Response payloads trimmed to needed fields
+- [ ] Compression enabled (gzip, brotli)
+- [ ] Connection pooling configured
+## Measurement Commands
+```bash
+# Lighthouse CLI
+npx lighthouse https://example.com --view
+# Web Vitals in browser
+# Chrome DevTools → Performance tab → Record
+# Bundle analysis
+npx webpack-bundle-analyzer stats.json
+# TTFB diagnosis in DevTools Network waterfall
+# Check: DNS → TCP/TLS → Server processing
+```
+## Common Anti-Patterns
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Loading all JS upfront | Slow FCP/TTI | Code split by route |
+| Unoptimized images | High LCP | Compress, modern formats, responsive sizes |
+| No caching headers | Repeat downloads | `Cache-Control` with content hashing |
+| Client-side rendering everything | Slow FCP, bad SEO | Server components, SSG where possible |
+| Third-party scripts in `<head>` | Blocks rendering | `async`/`defer`, audit, facade pattern |
+| Missing width/height on images | Layout shift (CLS) | Explicit dimensions or aspect-ratio |

package/dist/template/.pi/skills/planning-and-task-breakdown/SKILL.md ADDED Viewed

@@ -0,0 +1,204 @@
+---
+name: planning-and-task-breakdown
+description: Decomposes a spec into small verifiable tasks with dependencies and acceptance checks. Use when a feature/change has a spec or clear goal and needs an executable implementation plan.
+---
+# Planning & Task Breakdown
+## Overview
+A good plan creates leverage for builders. It says what must become true, where to work, what not to touch, and how to prove success.
+Core principle: plan backward from observable truths into artifacts, wiring, tasks, dependencies, and verification.
+Decompose work into small, verifiable tasks with explicit acceptance criteria. Good task breakdown is the difference between an agent that completes work reliably and one that produces a tangled mess. This skill is the canonical active planning skill. It absorbs PRD-to-plan and writing-plans responsibilities.
+## When to Use
+- A spec or clear goal exists and implementation is non-trivial.
+- Work spans multiple files, phases, or agents.
+- Tasks need dependency ordering or parallelization decisions.
+- You need a handoff artifact for worker agents.
+- Multiple acceptance criteria or subsystems are involved.
+- The work may span sessions and needs a durable record.
+## When NOT to Use
+- Single-file fixes that can be implemented directly.
+- Requirements are still unclear; use `spec-driven-development` first.
+- You are debugging an active failure; use `debugging-and-error-recovery`.
+- The user only asked for a quick estimate or feasibility check.
+## The Planning Process
+### Step 1: Enter Plan Mode — Read-only
+Read the spec, inspect the codebase, identify existing patterns, and map dependencies. Do NOT write implementation code. Read before you plan. Capture assumptions, unknowns, and constraints that could change the shape of the work.
+### Step 2: Identify the Dependency Graph
+Map what depends on what. Build foundations before features that rest on them. Mark risky unknowns and integration seams. Order matters. A dependency graph prevents you from discovering a blocker halfway through implementation.
+### Step 3: Slice Vertically
+Instead of building all DB, then all API, then all UI, build one complete feature path at a time. A vertical slice delivers a thin, working thread through the system — for example, creating one record end-to-end from UI through service to storage. Vertical slices produce end-to-end behavior and surface broken wiring early. Horizontal slices delay integration and hide problems until the end.
+### Step 4: Write Tasks
+Each task must include:
+- **Description:** one-sentence goal.
+- **Acceptance Criteria:** what must be true when done.
+- **Verification:** command, test, or check that proves it.
+- **Dependencies:** tasks that must finish first.
+- **Files Likely Touched:** paths or search targets when known.
+- **Estimated Scope:** XS / S / M / L / XL.
+Be specific. "Update backend" is not a task; "Add `createUser` mutation resolver with input validation" is.
+### Step 5: Order and Checkpoint
+Arrange tasks so dependencies are satisfied. Every checkpoint should leave a working state. Insert checkpoints every 2-3 tasks or at phase boundaries. A checkpoint means the code passes tests and can be reviewed as a coherent unit.
+## Workflow
+1. Restate the goal and constraints.
+2. Convert observable truths into required artifacts.
+3. Identify required wiring between artifacts.
+4. Mark key links most likely to break.
+5. Decompose into vertical slices, not horizontal layers.
+6. Limit each task to a small scope with exact files when known.
+7. Add acceptance checks and verification commands to every task.
+8. Build a dependency graph and execution order.
+9. Create tracked tasks or write a plan artifact.
+## Task Sizing Guidelines
+| Size | Files | Example |
+|------|-------|---------|
+| XS | 1 | Add a validation rule |
+| S | 1-2 | Add a new API endpoint |
+| M | 3-5 | One feature slice |
+| L | 5-8 | Multi-component feature |
+| XL | 8+ | Too large — break it down |
+Break down a task when any of the following is true:
+- It will take more than one session.
+- It has more than three acceptance criteria.
+- It touches two or more independent subsystems.
+- It likely touches more than five files.
+- It mixes refactoring with behavior changes.
+When in doubt, err toward smaller tasks. Small tasks are easier to verify, review, and recover from if they fail.
+## Plan Document Template
+A complete plan document should contain:
+1. **Overview** — what the plan achieves and why.
+2. **Architecture Decisions** — key choices and their rationale.
+3. **Task List** — ordered tasks grouped into phases with checkpoints.
+4. **Risks and Mitigations** — what could go wrong and how to handle it.
+5. **Open Questions** — anything that must be resolved before implementation.
+Keep the document focused. It is a contract for execution, not a design diary. Each phase should have a clear entry condition and exit criteria.
+## Task Packet Template
+```markdown
+## Task N: [Name]
+Goal: [one sentence]
+Files in scope:
+- [path]
+Acceptance checks:
+- [behavior] -> verify with [command/check]
+Non-goals:
+- [explicit exclusion]
+Dependencies:
+- [task id/name or none]
+Review depth: targeted|standard|full
+```
+Use the packet template when handing work to a worker agent or when tracking tasks in a plan document.
+## Slicing Rules
+- Prefer vertical slices that produce end-to-end behavior.
+- Put risky unknowns first.
+- Do not mix refactors with feature behavior unless the refactor is required.
+- If one task touches more than five files, split it.
+- If a task needs architectural judgment, route to `planner`, not `worker`.
+- Keep each task scoped to one coherent change.
+## Parallelization Opportunities
+| Type | Guidance |
+|------|----------|
+| Safe | Independent feature slices, tests, docs |
+| Must be sequential | Migrations, shared state, dependency chains |
+| Needs coordination | Shared API contracts (define the contract first) |
+When parallelizing, document file ownership and integration points. Multiple agents assigned to overlapping files without sequencing is a red flag. Parallel work still needs a single source of truth for ordering.
+## Common Rationalizations
+| Rationalization | Reality |
+|---|---|
+| "I'll figure it out as I go" | 10 minutes of planning saves hours of rework. |
+| "The tasks are obvious" | Write them down anyway. Explicit tasks surface hidden dependencies. |
+| "Planning is overhead" | Planning is the task. Implementation without a plan is just typing. |
+| "I can hold it all in my head" | Context windows are finite. Written plans survive session boundaries. |
+| "I'll make tasks as I go" | Hidden dependencies appear too late. Plan the graph first. |
+| "Layer-by-layer is cleaner" | Horizontal layers delay integration and hide broken wiring. |
+| "Acceptance criteria are obvious" | Workers need objective checks, not intent. |
+| "One big task is simpler" | Big tasks are hard to review, rollback, and verify. |
+## Red Flags
+- Starting implementation without a written task list.
+- Tasks named after vague activities like "update backend".
+- Tasks that say "implement the feature" without acceptance criteria.
+- No verification command or check per task.
+- UI, API, and data work split so nothing works until the end.
+- Multiple agents assigned to overlapping files without sequencing.
+- Plan omits non-goals or rollback considerations.
+- All tasks are XL-sized.
+- The first task requires further planning to begin.
+## Verification Checklist
+- [ ] Every task has acceptance criteria.
+- [ ] Every task has a verification step.
+- [ ] Task dependencies are identified and ordered correctly.
+- [ ] No task touches more than ~5 files.
+- [ ] Checkpoints exist between major phases.
+- [ ] The first task can be implemented without further planning.
+- [ ] Key links are identified for reviewer verification.
+- [ ] The human has reviewed and approved the plan.
+## Skill Result Contract
+```xml
+<skill_result>
+  <skill>planning-and-task-breakdown</skill>
+  <status>success|partial|blocked|failure</status>
+  <evidence>Plan/task packets include scope, dependencies, and verification</evidence>
+  <artifacts>Task ids or plan file path</artifacts>
+  <risks>Large tasks, unresolved dependencies, or none</risks>
+</skill_result>
+```
+## Consolidated Planning Workflow
+This is the canonical active planning skill. It absorbs PRD-to-plan and writing-plans responsibilities. Use `spec-driven-development` first when requirements are still unclear.
+Plans should include:
+- scope and non-goals;
+- ordered tasks with dependencies;
+- exact files or search targets when known;
+- acceptance checks per task;
+- review and verification gates;
+- handoff details for subagents with zero assumed context.

package/dist/template/.pi/skills/playwright/SKILL.md ADDED Viewed

@@ -0,0 +1,404 @@
+---
+name: playwright
+description: Use when running automated browser tests, taking screenshots, validating forms, or verifying UX flows. Playwright CLI for token efficiency with MCP fallback for complex exploration. Also covers agent-browser CLI alternative. MUST load before any automated browser testing.
+---
+# Playwright Browser Automation
+## When to Use
+- When you need automated browser testing, screenshots, or form workflows via Playwright CLI/MCP.
+## When NOT to Use
+- When you specifically need to control your existing Chrome session (use playwriter instead).
+## Quick Decision
+| Scenario                                                         | Use                                 |
+| ---------------------------------------------------------------- | ----------------------------------- |
+| Quick screenshots, simple forms, token efficiency                | **Playwright CLI**                  |
+| Native binary speed + persistent isolated daemon-backed sessions | **agent-browser CLI** (alternative) |
+| Complex exploratory testing, self-healing workflows              | **MCP**                             |
+---
+## CLI Mode (Recommended)
+The CLI approach is **token-efficient** - no large schemas or verbose accessibility trees in context. Best for most automation tasks.
+### Alternative: agent-browser CLI
+- `agent-browser` is a Playwright-based automation stack with a **Rust binary** front-end and a **Node.js daemon** back-end.
+- Commands execute through the native CLI while the daemon keeps browser state warm between calls.
+- Uses the same snapshot-ref interaction pattern (`snapshot` → `@eN` refs → `click/fill/...`) as Playwright workflows.
+- Prefer this alternative when you want native binary command performance on repeated operations.
+- Prefer this alternative when you need explicitly isolated named sessions backed by persistent daemons.
+- Good fit for multi-session parallel workflows where each session keeps independent browser/auth/storage state.
+- Keep defaulting to `playwright-cli` for broad compatibility and token-efficient standard flows.
+- Use MCP mode when you need richer introspection or complex exploratory automation.
+- Full command and options reference lives at: `./references/agent-browser-cli.md`.
+### Installation
+```bash
+npm install -g @playwright/cli@latest
+playwright-cli install --skills  # Optional: install for Claude/Copilot
+```
+### Core Workflow
+```
+# 1. Open browser and navigate
+bash({ command: "playwright-cli open https://example.com" })
+# 2. Get element refs (snapshot)
+bash({ command: "playwright-cli snapshot" })
+# 3. Interact using refs
+bash({ command: "playwright-cli fill e12 'test@example.com'" })
+bash({ command: "playwright-cli click e34" })
+# 4. Screenshot
+bash({ command: "playwright-cli screenshot --filename=/tmp/result.png" })
+```
+### Commands Reference
+#### Navigation
+| Command      | Description                              |
+| ------------ | ---------------------------------------- |
+| `open [url]` | Open browser, optionally navigate to URL |
+| `goto <url>` | Navigate to URL                          |
+| `close`      | Close the page/browser                   |
+| `go-back`    | Go back to previous page                 |
+| `go-forward` | Go forward to next page                  |
+| `reload`     | Reload current page                      |
+#### Interaction
+| Command                    | Description                               |
+| -------------------------- | ----------------------------------------- |
+| `snapshot`                 | Capture page snapshot to get element refs |
+| `type <text>`              | Type text into focused element            |
+| `fill <ref> <text>`        | Fill text into specific element           |
+| `click <ref> [button]`     | Click element (left/right/middle)         |
+| `dblclick <ref>`           | Double-click element                      |
+| `hover <ref>`              | Hover over element                        |
+| `drag <startRef> <endRef>` | Drag and drop                             |
+| `select <ref> <value>`     | Select dropdown option                    |
+| `check <ref>`              | Check checkbox/radio                      |
+| `uncheck <ref>`            | Uncheck checkbox                          |
+| `upload <file>`            | Upload file(s)                            |
+#### Keyboard
+| Command         | Description                            |
+| --------------- | -------------------------------------- |
+| `press <key>`   | Press key (e.g., `Enter`, `ArrowLeft`) |
+| `keydown <key>` | Hold key down                          |
+| `keyup <key>`   | Release key                            |
+#### Screenshots & PDF
+| Command                              | Description                |
+| ------------------------------------ | -------------------------- |
+| `screenshot [ref]`                   | Screenshot page or element |
+| `screenshot --filename=/tmp/out.png` | Save to specific path      |
+| `pdf`                                | Save page as PDF           |
+| `pdf --filename=page.pdf`            | Save PDF to specific path  |
+#### Tabs
+| Command              | Description    |
+| -------------------- | -------------- |
+| `tab-list`           | List all tabs  |
+| `tab-new [url]`      | Create new tab |
+| `tab-close [index]`  | Close tab      |
+| `tab-select <index>` | Switch to tab  |
+#### Storage
+| Command                          | Description                     |
+| -------------------------------- | ------------------------------- |
+| `cookie-list`                    | List cookies                    |
+| `cookie-get <name>`              | Get cookie value                |
+| `cookie-set <name> <value>`      | Set cookie                      |
+| `cookie-delete <name>`           | Delete cookie                   |
+| `cookie-clear`                   | Clear all cookies               |
+| `localstorage-list`              | List localStorage               |
+| `localstorage-get <key>`         | Get localStorage value          |
+| `localstorage-set <key> <value>` | Set localStorage                |
+| `sessionstorage-*`               | Same pattern for sessionStorage |
+#### Network
+| Command             | Description           |
+| ------------------- | --------------------- |
+| `route <pattern>`   | Mock network requests |
+| `route-list`        | List active routes    |
+| `unroute [pattern]` | Remove route(s)       |
+#### DevTools
+| Command                 | Description                         |
+| ----------------------- | ----------------------------------- |
+| `console [min-level]`   | List console messages               |
+| `network`               | List network requests               |
+| `eval <func> [ref]`     | Evaluate JavaScript on page/element |
+| `run-code <code>`       | Run Playwright code snippet         |
+| `tracing-start`         | Start trace recording               |
+| `tracing-stop`          | Stop trace recording                |
+| `video-start`           | Start video recording               |
+| `video-stop [filename]` | Stop video recording                |
+### CLI Options
+```bash
+# Headless mode
+playwright-cli open https://example.com --headless
+# Choose browser
+playwright-cli open https://example.com --browser=firefox
+# Emulate device
+playwright-cli open https://example.com --device="iPhone 14"
+# Named session (isolated browser)
+playwright-cli -s=project1 open https://example.com
+# See all options
+playwright-cli --help
+```
+### CLI Examples
+#### Test Responsive Design
+```typescript
+// Desktop
+bash({ command: "playwright-cli open http://localhost:3000" });
+bash({ command: "playwright-cli resize 1920 1080" });
+bash({ command: "playwright-cli screenshot --filename=/tmp/desktop.png" });
+// Mobile
+bash({ command: "playwright-cli resize 390 844" }); // iPhone 14
+bash({ command: "playwright-cli screenshot --filename=/tmp/mobile.png" });
+```
+#### Fill a Form
+```typescript
+bash({ command: "playwright-cli open http://localhost:3000/contact" });
+// Get snapshot to see element refs
+bash({ command: "playwright-cli snapshot" });
+// Fill using refs from snapshot output
+bash({ command: "playwright-cli fill e12 'John Doe'" });
+bash({ command: "playwright-cli fill e34 'john@example.com'" });
+bash({ command: "playwright-cli click e56" }); // Submit button
+// Wait for confirmation
+bash({ command: "playwright-cli eval 'document.body.innerText.includes(\"Thank you\")'" });
+```
+#### Multi-Step Login Flow
+```typescript
+bash({ command: "playwright-cli open https://app.example.com/login" });
+bash({ command: "playwright-cli snapshot" });
+bash({ command: "playwright-cli fill e10 'username'" });
+bash({ command: "playwright-cli fill e12 'password'" });
+bash({ command: "playwright-cli click e15" });
+// Verify logged in
+bash({ command: "playwright-cli eval 'document.querySelector(\".dashboard\") !== null'" });
+bash({ command: "playwright-cli screenshot --filename=/tmp/logged-in.png" });
+```
+#### Session Management
+```typescript
+// List all browser sessions
+bash({ command: "playwright-cli list" });
+// Use named session
+bash({ command: "playwright-cli -s=project1 open https://example.com" });
+// Close specific session
+bash({ command: "playwright-cli -s=project1 close" });
+// Close all browsers
+bash({ command: "playwright-cli close-all" });
+```
+---
+## MCP Mode (Fallback)
+Use MCP for complex exploratory workflows or when you need persistent browser state with rich introspection.
+### Tools (8 Essential)
+- `browser_navigate` - Navigate to URL
+- `browser_snapshot` - Get accessibility snapshot with element refs
+- `browser_take_screenshot` - Capture screenshot
+- `browser_click` - Click element by ref
+- `browser_type` - Type text (appends)
+- `browser_fill` - Fill input (clears first, then types)
+- `browser_wait_for` - Wait for text or selector
+- `browser_resize` - Resize viewport or emulate device
+### MCP Workflow
+```typescript
+// Navigate
+skill_mcp(
+  (skill_name = "playwright"),
+  (tool_name = "browser_navigate"),
+  (arguments = '{"url": "https://example.com"}'),
+);
+// Get element refs
+skill_mcp((skill_name = "playwright"), (tool_name = "browser_snapshot"));
+// Interact
+skill_mcp(
+  (skill_name = "playwright"),
+  (tool_name = "browser_click"),
+  (arguments = '{"element": "Submit", "ref": "e12"}'),
+);
+// Screenshot
+skill_mcp(
+  (skill_name = "playwright"),
+  (tool_name = "browser_take_screenshot"),
+  (arguments = '{"filename": "/tmp/result.png"}'),
+);
+```
+### MCP Configuration
+```json
+{
+  "playwright": {
+    "command": "npx",
+    "args": ["@playwright/mcp@latest"],
+    "includeTools": [
+      "browser_navigate",
+      "browser_snapshot",
+      "browser_take_screenshot",
+      "browser_click",
+      "browser_type",
+      "browser_fill",
+      "browser_wait_for",
+      "browser_resize"
+    ]
+  }
+}
+```
+---
+## Token Discipline (Snapshots / Console / Network)
+Browser introspection tools return huge payloads. A single `browser_snapshot` of a real app is routinely **50K–150K tokens**. A single full `browser_console_messages` or `browser_network_requests` can be similar. Pulling that raw into context wrecks the session.
+**Rule**: when an MCP browser tool supports a `filename` parameter, **always save to a file first, then read selectively**. Reserve direct (no-`filename`) calls for tiny pages or when you genuinely need the whole tree in context.
+### Tools that MUST use `filename` for non-trivial pages
+| Tool                       | When to use `filename`                                    |
+| -------------------------- | --------------------------------------------------------- |
+| `browser_snapshot`         | Always on real apps — accessibility trees explode in size |
+| `browser_take_screenshot`  | Always — never inline binary data                         |
+| `browser_console_messages` | When you expect >20 lines or you don't know the volume    |
+| `browser_network_requests` | When you expect >20 requests or full bodies               |
+| `browser_pdf_save`         | Always                                                    |
+### Pattern
+```typescript
+// 1. Save the heavy artifact to a file
+skill_mcp(
+  (skill_name = "playwright"),
+  (tool_name = "browser_snapshot"),
+  (arguments = '{"filename": "/tmp/snapshot.yaml"}'),
+);
+// 2. Search the file for what you actually need
+bash({ command: "grep -n -E 'role=button|role=textbox' /tmp/snapshot.yaml | head -40" });
+// 3. Read just the relevant slice
+read({ filePath: "/tmp/snapshot.yaml", offset: 120, limit: 40 });
+```
+CLI mode has the same discipline — `playwright-cli snapshot > /tmp/snap.yaml` then `grep`/`head`, never paste the whole snapshot into the conversation.
+### Anti-Patterns
+| Anti-Pattern                                                  | Cost                          | Fix                                                 |
+| ------------------------------------------------------------- | ----------------------------- | --------------------------------------------------- |
+| `browser_snapshot` with no `filename` on a real app           | 50K–150K tokens in one shot   | Add `filename`, then `grep` / `read` slice          |
+| `browser_console_messages` with no `filename` on a noisy page | Floods context with logs      | Add `filename`, `grep ERROR` after                  |
+| `browser_network_requests` with no `filename`                 | Hundreds of requests + bodies | Add `filename`, then filter by URL/status           |
+| Pasting full snapshot YAML into a follow-up prompt            | Re-bills the same tokens      | Reference the file path; re-read only what's needed |
+Adapted from the **context saving** discipline in [context-mode](https://github.com/mksglu/context-mode); their measurements show ~99% reduction (135K → ~250 bytes per snapshot) when using `filename` + selective reads.
+---
+## Best Practices
+1. **Default to CLI** for token efficiency
+2. **Snapshot before interact** - always get element refs first
+3. **Use named sessions** (`-s=`) for isolated browser contexts
+4. **Save outputs to /tmp** for easy access and cleanup
+5. **Use `filename` on heavy MCP tools** — see Token Discipline above
+6. **Check console/network** for debugging: `playwright-cli console error`
+7. **Use eval for custom checks** when built-in commands aren't enough
+## Troubleshooting
+| Issue               | Solution                                         |
+| ------------------- | ------------------------------------------------ |
+| Element not found   | Re-run snapshot to get fresh refs                |
+| Page not loading    | Check network with `playwright-cli network`      |
+| Timing issues       | Use `eval` to check conditions before proceeding |
+| Session conflicts   | Use named sessions (`-s=project1`)               |
+| Browser won't close | `playwright-cli kill-all` as last resort         |
+## References
+- [Playwright CLI GitHub](https://github.com/microsoft/playwright-cli)
+- [Playwright MCP GitHub](https://github.com/microsoft/playwright-mcp)
+- [Playwright Docs](https://playwright.dev)
+## Common Rationalizations
+| Rationalization | Reality |
+|---|---|
+| "The UI test is flaky, I'll skip it" | Flaky tests mask real bugs. Fix the flakiness, don't skip the test. |
+| "Visual testing is optional" | Visual regressions are the most common production bugs. Screenshot comparisons catch them. |
+| "I'll write E2E tests after the feature" | E2E tests written later are tests never written. Write alongside the feature. |
+## Red Flags
+- Tests that pass locally but fail in CI
+- Selectors using fragile CSS classes or XPaths
+- No wait strategies — relying on arbitrary timeouts
+- Tests without assertions (navigation only)
+- Screenshot comparisons without threshold tolerance
+## Verification
+After writing Playwright tests:
+- [ ] Tests pass consistently (not flaky) — run 3x to confirm
+- [ ] Selectors use data-testid or role-based queries (not fragile CSS classes)
+- [ ] Explicit wait strategies avoid arbitrary timeouts
+- [ ] Every test has at least one meaningful assertion
+- [ ] Visual regression tests have appropriate tolerance thresholds