@ytspar/sweetlink 1.16.0 → 1.17.0

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

@@ -1,6 +1,6 @@
 ---
 name: console-check-sweetlink
-description: Quick console error check using Sweetlink. Use after making code changes, before marking tasks complete, during debugging, or when the user asks to check for console errors. Essential for the zero-error policy.
+description: "Check browser console for errors/warnings via Sweetlink WebSocket. Triggers on: \"console errors\", \"browser errors\", \"console check\", \"zero errors\". NOT for TypeScript/compile errors (use quick-typecheck) or server-side errors (use debugging agent)."
 allowed-tools: Bash
 ---
 

package/claude-skills/console-check-sweetlink/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill_name": "console-check-sweetlink",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Check the browser console for errors",
+      "expected_output": "The skill uses Sweetlink to connect to the browser and retrieve console logs",
+      "expectations": [
+        "Uses Sweetlink WebSocket or logs command to read browser console",
+        "Filters for errors and warnings",
+        "Reports any console errors found or confirms zero errors"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Any console errors after my changes?",
+      "expected_output": "The skill checks the browser console for new errors via Sweetlink",
+      "expectations": [
+        "Triggers the console check flow via Sweetlink",
+        "Reports errors, warnings, or confirms clean console",
+        "Does not run TypeScript or lint checks"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Check for TypeScript errors",
+      "expected_output": "This should NOT trigger console-check-sweetlink. TypeScript errors are handled by quick-typecheck.",
+      "expectations": [
+        "Does NOT trigger console-check-sweetlink skill",
+        "Routes to quick-typecheck instead",
+        "No Sweetlink or browser commands are executed"
+      ]
+    }
+  ]
+}

package/claude-skills/resize-for-claude/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "resize-for-claude",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "This Figma export is 5120x11732 pixels, resize it so Claude can analyze it properly",
+      "expected_output": "Triggers resize-for-claude skill to scale the image down so the longest side is 1568px",
+      "expectations": ["Should trigger resize-for-claude skill", "Should run the resize-for-claude script", "Should detect tall aspect ratio and split into overlapping tiles if >= 3:1"]
+    },
+    {
+      "id": 2,
+      "prompt": "Optimize this full-page screenshot for Claude vision before I ask it to review the design",
+      "expected_output": "Triggers resize-for-claude skill to resize and potentially tile a tall screenshot",
+      "expectations": ["Should trigger resize-for-claude skill", "Should output to a -claude/ directory next to the original", "Should produce images with longest side <= 1568px"]
+    },
+    {
+      "id": 3,
+      "prompt": "Take a screenshot of the homepage at mobile, tablet, and desktop viewports",
+      "expected_output": "Should NOT trigger resize-for-claude - this is about capturing responsive screenshots, not resizing existing images",
+      "expectations": ["Should NOT trigger resize-for-claude - use responsive-screenshots for capturing at multiple viewports"]
+    }
+  ]
+}

package/claude-skills/responsive-screenshots/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: responsive-screenshots
-description: Capture screenshots at standard responsive breakpoints (mobile, tablet, desktop) to verify responsive design. Use when implementing responsive layouts, during design reviews, testing UI across viewports, or when the user asks to verify responsive behavior.
+description: "Capture screenshots at mobile/tablet/desktop breakpoints via Sweetlink. Triggers on: \"responsive screenshots\", \"test breakpoints\", \"check mobile/tablet/desktop\", \"viewport screenshots\". NOT for single screenshots (use screenshot) or Playwright-based design review (use design-review agent)."
 allowed-tools: Bash
 ---
 

package/claude-skills/responsive-screenshots/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "responsive-screenshots",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Capture responsive screenshots at mobile, tablet, and desktop to verify the new hero section",
+      "expected_output": "Triggers responsive-screenshots skill to capture at 375px, 768px, and 1440px viewports via Sweetlink",
+      "expectations": ["Should trigger responsive-screenshots skill", "Should capture at all three standard breakpoints (375, 768, 1440)", "Should save to .tmp/screenshots/ and review for responsive issues"]
+    },
+    {
+      "id": 2,
+      "prompt": "Test the breakpoints on the pricing page -- I want to see how it looks on mobile vs desktop",
+      "expected_output": "Triggers responsive-screenshots skill to capture the pricing page across viewports",
+      "expectations": ["Should trigger responsive-screenshots skill", "Should use pnpm sweetlink screenshot with --viewport flags", "Should analyze screenshots against the quality checklist"]
+    },
+    {
+      "id": 3,
+      "prompt": "Take a quick screenshot of the current page to verify my CSS change",
+      "expected_output": "Should NOT trigger responsive-screenshots - this is a single screenshot, not multi-viewport testing",
+      "expectations": ["Should NOT trigger responsive-screenshots - use screenshot skill for single screenshots"]
+    }
+  ]
+}

package/claude-skills/screenshot/SKILL.md

@@ -84,6 +84,8 @@ pnpm sweetlink screenshot --viewport mobile --force-cdp --output .tmp/screenshot
 
 ### Agent-Browser (Any URL)
 
+A live observability dashboard auto-opens at http://localhost:4848 on the user's first agent-browser command of a session (wired via PreToolUse hook in `~/.claude/settings.json`). Mention the URL when you start an agent-browser flow so the user can watch along.
+
 ```bash
 # Open page and screenshot
 agent-browser open http://localhost:3000

package/claude-skills/screenshot/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill_name": "screenshot",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Take a screenshot of the app",
+      "expected_output": "The skill uses Sweetlink to capture a screenshot of the running application",
+      "expectations": [
+        "Uses Sweetlink screenshot command to capture the current page",
+        "Returns or saves the screenshot image",
+        "Does not use Playwright or other browser automation"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Screenshot the homepage",
+      "expected_output": "The skill captures a screenshot of the specified page (homepage)",
+      "expectations": [
+        "Navigates to or targets the homepage URL/path",
+        "Uses Sweetlink screenshot command",
+        "Returns the captured screenshot for review"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Take screenshots at mobile, tablet, and desktop breakpoints",
+      "expected_output": "This should NOT trigger the single screenshot skill. Multi-viewport screenshots are handled by responsive-screenshots.",
+      "expectations": [
+        "Does NOT trigger screenshot skill for multi-viewport capture",
+        "Routes to responsive-screenshots instead",
+        "Single screenshot skill handles only one viewport at a time"
+      ]
+    }
+  ]
+}

package/dist/cli/sweetlink.js

@@ -14,6 +14,7 @@ import { getCardHeaderPreset, getNavigationPreset, measureViaPlaywright } from '
 import { DEFAULT_WS_PORT, MAX_PORT_RETRIES, WS_PORT_OFFSET } from '../types.js';
 import { SCREENSHOT_DIR } from '../urlUtils.js';
 import { daemonRequest, ensureDaemon, getDaemonStatus, stopDaemon } from '../daemon/client.js';
+import { extractPort } from '../daemon/stateFile.js';
 import { uploadEvidence } from '../daemon/evidence.js';
 import { emitJson, printOutputSchema } from './outputSchemas.js';
 const COMMON_APP_PORTS = [3000, 3001, 4000, 5173, 5174, 8000, 8080];
@@ -457,12 +458,25 @@ async function screenshot(options) {
             selector: options.selector,
             fullPage: options.fullPage,
             viewport: options.viewport,
+            padding: options.padding,
         });
         const data = resp.data;
         const outputPath = options.output || getDefaultScreenshotPath();
         ensureDir(outputPath);
         fs.writeFileSync(outputPath, Buffer.from(data.screenshot, 'base64'));
         reportScreenshotSuccess(outputPath, data.width, data.height, 'Daemon (hifi)', options.selector);
+        // UX: warn about silent .first() when multiple elements match.
+        if (options.selector && data.matchCount && data.matchCount > 1) {
+            console.warn(`[Sweetlink] ⚠ Selector '${options.selector}' matched ${data.matchCount} elements; captured the first. ` +
+                `Use --index N (with click) or a more specific selector to pick another.`);
+        }
+        // UX: hint at --full-page when content extends below the viewport.
+        if (!options.selector && !options.fullPage &&
+            data.pageHeight && data.viewportHeight && data.pageHeight > data.viewportHeight + 4) {
+            const overflow = data.pageHeight - data.viewportHeight;
+            console.log(`[Sweetlink] ℹ Page extends ${overflow}px below the viewport. ` +
+                `Use --full-page to capture all of it.`);
+        }
         return {
             path: getRelativePath(outputPath),
             width: data.width,
@@ -2116,6 +2130,7 @@ async function handleStatusCommand() {
                     width: getArg('--width') ? parseInt(getArg('--width'), 10) : undefined,
                     height: getArg('--height') ? parseInt(getArg('--height'), 10) : undefined,
                     hover: hasFlag('--hover'),
+                    padding: getArg('--padding') ? parseInt(getArg('--padding'), 10) : undefined,
                     url: getArg('--url'),
                     wait: !hasFlag('--no-wait'), // Wait by default, --no-wait to skip
                     waitTimeout: getArg('--wait-timeout')
@@ -2180,22 +2195,50 @@ async function handleStatusCommand() {
             }
             case 'click': {
                 const clickTarget = getArg('--selector') ?? args[1];
+                const clickText = getArg('--text');
+                const clickIndex = getArg('--index') ? parseInt(getArg('--index'), 10) : 0;
+                const projRoot = findProjectRoot();
+                const targetUrl = getArg('--url') ?? 'http://localhost:3000';
                 // Route @e refs to daemon
                 if (clickTarget && /^@e\d+$/.test(clickTarget)) {
-                    const projRoot = findProjectRoot();
-                    const targetUrl = getArg('--url') ?? 'http://localhost:3000';
                     const state = await ensureDaemon(projRoot, targetUrl);
                     await daemonRequest(state, 'click-ref', { ref: clickTarget });
                     console.log(`[Sweetlink] Clicked ${clickTarget}`);
                     result = { clicked: clickTarget, found: 1, index: 0 };
+                    break;
                 }
-                else {
-                    result = await click({
-                        selector: clickTarget,
-                        text: getArg('--text'),
-                        index: getArg('--index') ? parseInt(getArg('--index'), 10) : undefined,
-                    });
+                // If a recording is in progress, route CSS clicks through the daemon
+                // so they target the recording page (which has no devbar/WebSocket
+                // bridge) and get logged into the session manifest.
+                try {
+                    const status = await getDaemonStatus(projRoot, extractPort(targetUrl));
+                    if (status.running) {
+                        const state = await ensureDaemon(projRoot, targetUrl);
+                        const recStatus = await daemonRequest(state, 'record-status');
+                        const recData = recStatus.data;
+                        if (recData?.recording) {
+                            const resp = await daemonRequest(state, 'click-css', {
+                                selector: clickTarget,
+                                text: clickText,
+                                index: clickIndex,
+                            });
+                            const data = resp.data;
+                            console.log(`[Sweetlink] Clicked (recording): ${data.clicked ?? clickTarget ?? clickText}`);
+                            result = {
+                                clicked: data.clicked ?? 'unknown',
+                                found: data.found ?? 1,
+                                index: data.index ?? clickIndex,
+                            };
+                            break;
+                        }
+                    }
                 }
+                catch { /* fall through to WS path */ }
+                result = await click({
+                    selector: clickTarget,
+                    text: clickText,
+                    index: clickIndex,
+                });
                 break;
             }
             case 'network': {
@@ -2624,13 +2667,18 @@ async function handleStatusCommand() {
             case 'daemon': {
                 const subcommand = args[1];
                 const projRoot = findProjectRoot();
+                // Daemon state files are scoped by app port (`daemon-<port>.json`),
+                // so honour --url for status/stop too — otherwise they look up the
+                // un-suffixed `daemon.json` and miss the daemon that `start`
+                // wrote with --url.
+                const targetUrl = getArg('--url') ?? 'http://localhost:3000';
+                const appPort = extractPort(targetUrl);
                 if (subcommand === 'stop') {
-                    const stopped = await stopDaemon(projRoot);
+                    const stopped = await stopDaemon(projRoot, appPort);
                     console.log(stopped ? '[Sweetlink] Daemon stopped.' : '[Sweetlink] No daemon running.');
                     result = { running: false };
                 }
                 else if (subcommand === 'start') {
-                    const targetUrl = getArg('--url') ?? 'http://localhost:3000';
                     const headedFlag = hasFlag('--headed');
                     const state = await ensureDaemon(projRoot, targetUrl, { headed: headedFlag });
                     console.log(`[Sweetlink] Daemon running on port ${state.port} (PID: ${state.pid})`);
@@ -2643,7 +2691,7 @@ async function handleStatusCommand() {
                 }
                 else {
                     // Default: status
-                    const status = await getDaemonStatus(projRoot);
+                    const status = await getDaemonStatus(projRoot, appPort);
                     if (status.running) {
                         console.log(`[Sweetlink] Daemon running: port=${status.port} pid=${status.pid} uptime=${status.uptime}s`);
                     }
@@ -2732,7 +2780,17 @@ async function handleStatusCommand() {
             });
             origExit(1);
         }
-        console.error('[Sweetlink] Fatal error:', error);
+        // For Error objects, print just the message — the stack is rarely useful
+        // to end users and clutters the output. Set SWEETLINK_DEBUG=1 to see it.
+        if (error instanceof Error) {
+            console.error(`[Sweetlink] ${error.message}`);
+            if (process.env.SWEETLINK_DEBUG === '1' && error.stack) {
+                console.error(error.stack);
+            }
+        }
+        else {
+            console.error('[Sweetlink] Fatal error:', error);
+        }
         process.exit(1);
     }
 })();