Playwright Vision Low Resource

Playwright + Vision Low-Resource Profile

Purpose

Stabilize browser automation and visual analysis on low-memory environments without sacrificing verification quality.

This skill is global (user-level) and intended for reuse across all repositories.

Trigger conditions

Use this skill when any of the following apply:

• RAM <= 8 GB total
• Repeated error: Target page, context or browser has been closed
• VS Code extension host instability or OOM events
• Need reliable visual checks with constrained local resources

Hard constraints

1. No unbounded retries.
2. Max browser-context retries: 2.
3. Prefer workers=1 for local runs.
4. Prefer single-browser project (Chromium) locally.
5. Collect heavy artifacts only on failure/retry.

Standard operating profile

1) Environment preflight (always first)

Run:

• ~/.copilot/skills/playwright-vision-low-resource/scripts/preflight-playwright-mcp.sh

If available memory is low (< 1.5 GB), do not start headed or multi-worker runs.

2) MCP profile (workspace)

For .vscode/mcp.json prefer:

• --headless
• --isolated
• --no-sandbox
• bounded --timeout-navigation and --timeout-action
• file output mode and explicit output dir

Template: ./templates/mcp.low-resource.jsonc

3) Playwright profile (workspace)

For local constrained runs:

• workers: 1
• maxFailures: 1
• single local project (chromium)
• trace: 'on-first-retry'
• video: 'retain-on-failure'
• screenshot: 'only-on-failure'

Template: ./templates/playwright.low-resource.config.ts

4) Vision profile

For Claude vision calls:

• Prefer image long edge <= 1568 px
• Avoid tiny images (< 200 px edge)
• Use 1-3 targeted screenshots per question (not full dumps)
• Prefer viewport/element screenshots over full-page unless layout context is required

5) Failure protocol

If browser-context loss occurs twice in a row:

• Stop browser retries
• Switch to deterministic fallback:
  • HTML fetch / DOM inspection
  • targeted CSS/JS edits
  • CI/quality-gate verification
• Mark visual verification as deferred/manual if required

Mode guidance

• mode=local-smoke: fastest, minimal artifacts, single worker
• mode=local-debug: still single worker, enable traces/videos on failure
• mode=remote-full: run full matrix in remote/CI environment; keep local machine for orchestration only

Output contract (when invoked)

Return:

1. Current risk classification (low|medium|high)
2. Exact profile selected (local-smoke|local-debug|remote-full)
3. Minimal file/settings deltas required
4. Verification plan with objective pass/fail checks

Automation helper

To scaffold low-resource defaults into the current repo:

• ~/.copilot/skills/playwright-vision-low-resource/scripts/apply-workspace-lowram.sh <workspace-path>

Behavior:

• If .vscode/mcp.json exists, it is backed up and a recommended low-resource file is written as .vscode/mcp.low-resource.recommended.json.
• If .vscode/mcp.json does not exist, it is created from template.
• Creates playwright.low-resource.config.ts if missing.

System daemon interop (§6 — Watchdog pause pattern)

Problem

On machines running a PSI-aware memory watchdog (e.g. a systemd --user service that monitors VS Code RSS and free-RAM percentage), the watchdog's RSS acceleration trigger fires continuously during active VS Code sessions — even when overall free RAM is healthy. It SIGTERMs helper processes (tsserver, extension host workers) every 40–90 s. When Playwright launches Chrome for a ≥60 s automation run, the watchdog SIGTERM hits the browser before the save/verify cycle completes, causing silent or explicit mid-run failures.

Symptom pattern:

• Terminal exits with code 0 or non-zero before publish log prints final ✅ lines
• sq-error-*.png screenshots show partially-saved state
• journalctl --user -u mem-watchdog --since "5 min ago" shows SIGTERM events coinciding with Chrome launch

Diagnosis steps

1. Check watchdog status:

   systemctl --user status mem-watchdog
   

2. Confirm ACCEL trigger is firing:

   journalctl --user -u mem-watchdog -n 40 | grep -E "ACCEL|SIGTERM|SIGKILL|RSS"
   

3. If ACCEL events appear within 90 s of the publish attempt → watchdog is the cause.

Solution: stop → run → restart

# 1. Stop watchdog (safe for ≤5 min publish window)
systemctl --user stop mem-watchdog

# 2. Run automation headless with bundled browser (minimum overhead)
DEPLOY_TARGET=uat USE_SYSTEM_CHROME=0 node scripts/publish-to-squarespace.js

# 3. Restart watchdog immediately after
systemctl --user start mem-watchdog && systemctl --user is-active mem-watchdog

Why it is safe to pause: The system-level swap (e.g. 16 GB zram on ChromeOS/Crostini) provides OOM protection during the ~60–90 s gap. The watchdog pause is bounded; do not leave it stopped for more than ~5 minutes.

Hard constraints

• Never permanently disable the watchdog — only pause for the automation window.
• Always confirm is-active mem-watchdog returns active before ending the session.
• Prefer USE_SYSTEM_CHROME=0 (bundled Chromium) and HEADED=0 (headless default) to minimise peak RSS during the window.

Trigger conditions (additions to §§ above)

Also apply this skill when:

• A systemd --user memory watchdog is active on the machine
• journalctl shows SIGTERM/SIGKILL events near Chrome launch timestamps
• Browser automation exits prematurely with no JS-level error (watchdog kill leaves no in-process trace)

MCP/Vision interoperability findings (§7 — 2026-03 hardening update)

A) Why Claude Vision text can appear “missing” in tool responses

Confirmed behavior in VS Code MCP stack: when a tool returns both content[].text and structuredContent, model-visible payload handling may prioritize/replace with structured data, causing the natural-language analysis text to be hidden or degraded for agent reasoning.

Reference:

• VS Code issue: https://github.com/microsoft/vscode/issues/290063

Practical rule: for LLM-readable analysis tools, keep the primary analysis in content[].text and avoid relying on structuredContent to carry critical narrative.

B) content array is still required

Even when returning structured data, keep content present (empty is allowed by maintainers; non-empty text is preferred for reliability and debugging UX).

Reference:

• VS Code issue: https://github.com/microsoft/vscode/issues/297669

C) envFile semantics in VS Code MCP

envFile variables are loaded into the spawned MCP process environment, but ${env:VAR} substitution in mcp.json happens earlier and does not read values from envFile.

References:

• Feature merged: https://github.com/microsoft/vscode/pull/244059
• Behavior clarification: https://github.com/microsoft/vscode/issues/250074

D) Playwright browser-closed errors are often host-level kills, not MCP logic bugs

Target page, context or browser has been closed is frequently a symptom of external process termination (OOM watchdog / cgroup / host kill). Retry once; if it repeats, treat as infrastructure pressure and apply watchdog pause protocol.

Reference:

• Playwright MCP issue example: https://github.com/microsoft/playwright-mcp/issues/1381

E) Stable operating sequence for Claude Visualization on low-RAM Linux

1. Stop watchdog:
   • systemctl --user stop mem-watchdog
2. Run visual MCP capture/analyze calls (bounded count, targeted scope).
3. Restart watchdog:
   • systemctl --user start mem-watchdog && systemctl --user is-active mem-watchdog

Never leave watchdog disabled after verification.

F) Recommended workspace MCP profile adjustments

• Prefer persistent profile over --isolated for iterative debugging:
  • --user-data-dir <workspace>/.playwright-mcp/profile
• Keep:
  • --headless
  • --no-sandbox (Linux containers as needed)
  • bounded navigation/action timeouts
• For vision-analysis MCP servers, include bounded retry (max 2) for browser-closed failures and emit failure text with attempt count.

G) Required response contract for vision analysis tools

For every analysis tool result, return model-readable text in content[].text with:

1. Human-readable verdict
2. Specific UX/readability findings
3. Compact metadata block (model/stop_reason/token counts)

Do not store critical analysis only in structuredContent.

Mandatory visual publish gate (§8 — required before publish/deploy sign-off)

For any workflow that changes UX-rendered assets (CSS, page blocks, injection HTML/JS, templates):

1. Do not declare publish success from DOM checks alone.
2. Run Claude Vision inspection at least once on the live/UAT URL after publish.
3. Required minimum pass criteria:
   • Hero/primary above-the-fold section is visibly rendered (no blank/collapsed viewport)
   • Primary CTA is visible and legible
   • No major section collapse/missing blocks in first full-page capture
   • No unreadable foreground/background contrast regressions
4. If Vision and DOM checks disagree, treat result as fail until reconciled with a second capture.
5. If visual verification cannot be completed (infra instability, browser kill), outcome must be:
   • publish: unverified
   • explicit blocker details
   • next verification action

Required verification evidence block

Every publish-touching task must include:

• URL inspected
• capture mode (viewport or fullPage)
• Vision verdict (pass|fail)
• top defects list (or none)

No evidence block → no success claim.

Squarespace LESS safety rules (§9 — compiler-compat guardrail)

When targeting Squarespace custom CSS (LESS-processed pipeline):

1. Do not use CSS custom property var(...) inside transition: shorthand values.
2. Do not use CSS custom property var(...) inside animation: shorthand values.
3. Prefer explicit literal timing values in shorthands (e.g. 150ms, 240ms).
4. If variables are desired, use them in non-shorthand properties where parser behavior is stable.

Mandatory compilation health check (post-publish)

After publish, fetch live site.css and fail if parse errors are present.

Fail patterns include (case-insensitive):

• SyntaxError
• INCOMPLETE_PARSE
• Unable to complete parse

If any fail pattern appears: rollback/fix CSS and republish before closing the task.