@ytspar/sweetlink 1.24.2 → 1.24.5-canary.765d8f8

package/claude-context/ui-verification-mandate.md

@@ -10,6 +10,28 @@ After implementing any visual/UI changes, you MUST:
 2. **Compare before/after** when making layout or styling changes
 3. **Verify at multiple viewports** for responsive design changes (mobile, tablet, desktop)
 
+## Coverage — scale verification to the change
+
+Screenshots must show the change **where it actually appears in the running
+app, in context** — verifying a component only in isolation (a component
+library / gallery view) is a *secondary* source, never the only proof. Scale
+coverage to the change:
+
+- **New or edited page / view** → capture it **in context** in the running app.
+- **Interactive element** → capture each meaningful **state** (default, hover,
+  focus, validation-error, empty, loading, disabled) as a named shot.
+- **Multi-step or branching element** (wizard, stepper, multi-stage modal,
+  branching form) → walk and capture **every step and every branch** ("all
+  paths"), not just the entry state. Use Playwright MCP to drive each path.
+- **New feature with a complex multi-stage process** → produce a **storyboard**:
+  an ordered screenshot sequence documenting the whole journey end to end.
+- **Reuse before create** → before adding an e2e spec for an affected area,
+  search the existing test suite and **expand or improve** a spec that already
+  covers it rather than writing a duplicate. Add a new spec only when none exists.
+- **Specs are durable, reusable assets** → capture specs are committed to the
+  project's e2e suite (not one-off throwaways), named by the affected area, and
+  runnable standalone so they re-verify in CI and on every future change.
+
 ## Tools
 
 ### Sweetlink (Quick Verification)

package/claude-skills/console-check-sweetlink/SKILL.md

@@ -6,325 +6,105 @@ allowed-tools: Bash
 
 # Console Check Sweetlink Skill
 
-Quickly check browser console for errors and warnings using Sweetlink's real-time log monitoring.
+Fast browser-console verification using Sweetlink's real-time log capture. Enforces the **zero-error policy** before marking a task complete or committing.
 
-## Purpose
+> Sweetlink architecture, prerequisites, daemon ring buffer, and setup are documented in [@ytspar/sweetlink's canonical context](../../claude-context/sweetlink-architecture.md). This skill assumes that context is loaded. The skill-specific scope is *when to check the console*, *which filter to use*, and *how to interpret results*.
 
-This skill provides a fast way to verify there are no console errors in the running application. It's essential for maintaining code quality and catching runtime issues immediately after making changes.
+## When to invoke (automatic)
 
-## When to Use
+- After any code change (catch errors immediately)
+- Before marking a task complete (zero-error policy)
+- After every screenshot (pair with `screenshot` skill — visual + console)
+- User reports unexpected behavior, asks to "check console", or mentions runtime bugs
+- Before committing code; during code reviews
 
-**Automatically use this skill when:**
-
-- After making ANY code changes (catch errors immediately)
-- Before marking a task as complete (zero errors policy)
-- User reports unexpected behavior or bugs
-- During debugging workflows
-- After deploying new features
-- User asks to "check console" or "check for errors"
-- Before committing code
-- During code reviews
-
-## How It Works
-
-Sweetlink maintains a real-time connection to the browser and captures all console messages. This skill:
-
-1. Queries Sweetlink for recent console logs
-2. Filters for errors (and optionally warnings)
-3. Returns a summary with error details
-4. Helps identify the root cause quickly
-
-## Commands
-
-### Check for Errors Only
+## Commands — call patterns
 
 ```bash
+# Errors only (default check)
 pnpm sweetlink logs --filter error
-```
-
-### Check for Errors and Warnings
 
-```bash
+# Errors + warnings (stricter)
 pnpm sweetlink logs --filter error && pnpm sweetlink logs --filter warning
-```
 
-### Get All Console Logs
+# LLM-optimized summary (deduped JSON — best for analysis)
+pnpm sweetlink logs --format summary
 
-```bash
-pnpm sweetlink logs
-```
+# Deduplicate noisy repeated messages (text mode)
+pnpm sweetlink logs --dedupe
 
-### Filter by Specific Term
-
-```bash
-pnpm sweetlink logs --filter "API"
+# Search for a specific term
+pnpm sweetlink logs --filter "hydration"
 pnpm sweetlink logs --filter "Failed to"
-pnpm sweetlink logs --filter "undefined"
-```
-
-## Understanding Console Errors
-
-### Common Error Types
-
-**1. TypeError - Type-related errors**
-
-```text
-TypeError: Cannot read property 'data' of undefined
-TypeError: undefined is not a function
-```
-
-**2. ReferenceError - Variable not defined**
-
-```text
-ReferenceError: myVariable is not defined
-```
-
-**3. Hydration Errors (React/SSR)**
-
-```text
-Warning: Text content did not match. Server: "..." Client: "..."
-Error: Hydration failed because the initial UI does not match...
-```
-
-**4. Network Errors**
-
-```text
-Failed to fetch
-NetworkError when attempting to fetch resource
-```
-
-**5. React Errors**
-
-```text
-Warning: Each child in a list should have a unique "key" prop
-Error: Maximum update depth exceeded
-```
-
-## Output Format
-
-### Zero Errors (Success)
-
-```text
-✅ Console Check: CLEAN
-
-Errors: 0
-Warnings: 0
-Status: Ready for commit ✓
-
-The application has no console errors. Zero-error policy maintained.
-```
-
-### Errors Found
-
-```markdown
-❌ Console Check: ERRORS FOUND
-
-Errors: 3
-Warnings: 1
-
-### Errors:
-
-1. [ERROR] TypeError: Cannot read property 'data' of undefined
-   Location: Card.tsx:45
-   Timestamp: 14:23:15.234
-
-2. [ERROR] Failed to fetch data from API
-   Location: api.ts:89
-   Timestamp: 14:23:16.891
-
-3. [ERROR] Hydration failed: content mismatch
-   Location: page.tsx:12
-   Timestamp: 14:23:17.023
-
-### Warnings:
-
-1. [WARN] Missing key prop in list rendering
-   Location: List.tsx:34
-   Timestamp: 14:23:15.456
-
-### Recommendations:
-- Fix null safety in Card.tsx (add null check for data)
-- Add error handling to API fetch in api.ts
-- Fix hydration by ensuring SSR/client consistency in page.tsx
-- Add unique keys to list items in List.tsx
-```
-
-## Best Practices
-
-### Development Workflow
-
-```bash
-# 1. Check baseline (before making changes)
-pnpm sweetlink logs --filter error
-# Should show 0 errors
-
-# 2. Make code changes
-
-# 3. Wait for HMR reload (2-3 seconds)
-
-# 4. Check for new errors immediately
-pnpm sweetlink logs --filter error
+pnpm sweetlink logs --filter "MyComponent"
 
-# 5. If errors found, fix immediately
-# 6. Repeat until 0 errors
+# Ring-buffer view from daemon (captured since daemon start)
+pnpm sweetlink console --errors
+pnpm sweetlink console --last 20
 ```
 
-### Before Committing
+Full flag reference for `logs` / `console` → run `pnpm sweetlink <cmd> --help` (authoritative, always live).
 
-```bash
-# Always check console before commit
-pnpm sweetlink logs --filter error
+## Zero-error policy
 
-# Only commit if 0 errors
-git commit -m "Add feature (0 console errors)"
-```
+Before marking ANY task complete:
 
-### During Code Review
+1. Run the error check.
+2. If non-zero: fix immediately, re-check until clean.
+3. Only then mark complete or commit.
 
-```bash
-# Check PR branch for console errors
-git checkout pr-branch
-pnpm sweetlink logs --filter error
-```
+A change with passing tests + a clean screenshot but console errors is **not done**.
 
-## Integration with Other Skills
+## Common error categories and the typical fix shape
 
-**Works well with:**
+| Pattern | Example | Typical fix |
+|---------|---------|-------------|
+| **TypeError — null/undefined access** | `Cannot read property 'data' of undefined` | Optional chaining `user?.name`, default values |
+| **ReferenceError** | `myVariable is not defined` | Missing import, typo, scope issue |
+| **Hydration mismatch** (SSR) | `Hydration failed because the initial UI does not match` | Move client-only values into `useEffect`; check date/random/locale in render |
+| **Network failure** | `Failed to fetch` | Add `.catch()`, check endpoint, CORS |
+| **React: missing key** | `Each child in a list should have a unique "key" prop` | Add stable `key` on mapped JSX |
+| **React: update loop** | `Maximum update depth exceeded` | Effect-loop — fix dependency array or setState in render |
 
-- `quick-typecheck` - Check both compile-time and runtime errors
-- `screenshot` - Visual verification + console check
-- `responsive-screenshots` - Check errors across viewports
+## Output expectations
 
-**Complete quality check:**
+**Clean state (target):**
 
-```bash
-# 1. Type errors (compile-time)
-pnpm run typecheck
-
-# 2. Console errors (runtime)
-pnpm sweetlink logs --filter error
-
-# 3. Visual verification
-pnpm sweetlink screenshot --output .tmp/screenshots/verify.png
-
-# If all pass: ✅ Ready to commit
 ```
-
-## Common Error Patterns
-
-### Pattern 1: Null/Undefined Access
-
-```javascript
-// Error: Cannot read property 'name' of undefined
-const name = user.name;
-
-// Fix: Add null check
-const name = user?.name;
+✅ Console Check: CLEAN — Errors: 0, Warnings: 0 → ready for commit
 ```
 
-### Pattern 2: Hydration Mismatch
+**With findings — report shape:**
 
-```javascript
-// Error: Hydration failed
-<div>{new Date().toString()}</div>
-
-// Fix: Use useEffect for client-only values
-const [time, setTime] = useState('');
-useEffect(() => setTime(new Date().toString()), []);
 ```
+❌ Console Check: ERRORS FOUND — Errors: N, Warnings: M
 
-### Pattern 3: Missing Error Handling
-
-```javascript
-// Error: Unhandled promise rejection
-fetch('/api/data');
-
-// Fix: Add error handling
-fetch('/api/data').catch(err => console.error(err));
+Errors:
+1. [ERROR] <message> — <file>:<line> — <timestamp>
+   ...
+Recommendation: <one line per finding>
 ```
 
-## Troubleshooting
-
-### "No browser client connected"
-
-**Solution:**
+Always group findings, cite source location when surfaced, and propose the fix.
 
-```bash
-# 1. Start dev server
-pnpm run dev
-
-# 2. Open browser at http://localhost:3000
-# 3. Look for Sweetlink connection indicator (bottom-right)
-```
+## Composition with other skills
 
-### Old Errors Showing
+- **`screenshot`** — every screenshot pairs with `logs --filter error` and `--filter warning`. Visual + console = verification.
+- **`quick-typecheck`** — compile-time errors. Combine: `pnpm run typecheck && pnpm sweetlink logs --filter error`.
+- **`responsive-screenshots`** — check console at each viewport (errors can be viewport-specific via media queries / matchMedia).
 
-**Solution:**
+Complete quality gate:
 
 ```bash
-# Hard refresh browser to clear cache
-# Mac: Cmd + Shift + R
-# Windows/Linux: Ctrl + Shift + R
+pnpm run typecheck                                            # 1. types
+pnpm sweetlink logs --filter error                            # 2. runtime
+pnpm sweetlink screenshot --output .tmp/screenshots/check.png # 3. visual
 ```
 
-### Too Many Logs
-
-**Solution:**
-
-```bash
-# Filter to focus on errors only
-pnpm sweetlink logs --filter error
-
-# Or search for specific term
-pnpm sweetlink logs --filter "MyComponent"
-```
-
-## Zero-Error Policy
-
-This skill enforces the zero-error policy:
-
-**Before marking ANY task complete:**
-
-1. Run console check
-2. Ensure 0 errors
-3. If errors found, fix them
-4. Re-check until clean
-5. Only then mark task as complete
-
-**Why this matters:**
-
-- Prevents bugs from accumulating
-- Catches issues immediately
-- Maintains code quality
-- Improves user experience
-- Reduces debugging time later
-
-## Quick Reference
-
-### Fast Error Check
-
-```bash
-pnpm sweetlink logs --filter error
-```
-
-### Full Console Analysis
-
-```bash
-pnpm sweetlink logs
-```
-
-### Search Specific Issue
-
-```bash
-pnpm sweetlink logs --filter "hydration"
-```
-
-### Check Warnings Too
-
-```bash
-pnpm sweetlink logs --filter warning
-```
+## Troubleshooting (skill-scoped)
 
-## Examples
+- **"No browser client connected"** — start dev server, open the URL, confirm Sweetlink indicator (bottom-right) before re-running.
+- **Old errors persist after a fix** — hard refresh the browser tab (`Cmd+Shift+R` mac / `Ctrl+Shift+R` win/linux) to clear stale state.
+- **Too many logs to read** — switch to `--format summary` (deduped JSON) or narrow with `--filter <term>`.
 
-See `examples.md` for detailed usage scenarios.
+Daemon-not-running / bridge-not-mounted / port-conflict → see the canonical context.