cssprobe-cli 0.2.24 → 0.2.26

package/AGENTS.md

@@ -47,7 +47,7 @@ src/
 - **Command dispatch**: `minimist` parse → `parseCommand()` Zod validate → session command execution via daemon socket.
 - **Output strategy**: `Output` interface → `TextOutput` (Markdown for inspect, tables for lists) / `JsonOutput` (machine-readable JSON).
 - **Config priority**: CLI flags → env vars → `~/.cssprobe-clirc` profiles. Switch with `-p <profile>`.
-- **State management**: `state-import` converts Netscape cookies. Session persists browser state until `close`.
+- **State management**: `state-import` converts Netscape cookies; `state-save` persists the current session's cookies + localStorage after manual login. Session persists browser state until `close`.
 - **Browser discovery**: `findBrowserExecutable()` scans `~/Library/Caches/ms-playwright/chromium-*` for existing Chrome installations.
 - **Error format**: `Error: <message>` → JSON mode: `{ isError: true, error: "<message>" }` → `process.exit(1)`
 
@@ -72,14 +72,19 @@ src/
 ### Browser
 - `resize <width> <height>` — Resize browser viewport
 - `eval <expression>` — Evaluate JavaScript (browser context)
+  - Returns raw string values (not JSON-quoted) for string results
 - `playwright <call>` — Execute Playwright API call (Node.js context)
+  - Returns `{ ok: true, value: null, note: ... }` when the call returns no value; throws a clear error message on failure
 - `screenshot` — Take a screenshot
+  - `--out <path>` — Output file path (default: `~/.cssprobe-cli/screenshots/<timestamp>.png`)
 
 ### State
 - `state-import [file]` — Import cookies from Netscape format
   - `--out <file>` — Output state file path (default: `~/.cssprobe-cli/states/imported.json`)
   - `--name <name>` — Custom name for the state file (e.g. `mysite` or `mysite.json`)
   - `--merge <file>` — Existing state file to merge into
+- `state-save` — Save current browser session state (cookies + localStorage)
+  - `--name <name>` — State file name (default: `session`)
 
 ### Config
 - `config-show` / `config-set` / `config-list` / `config-use` / `config-new` / `config-path`

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes are documented on the [GitHub Releases](https://github.com/mack-peng/cssprobe-cli/releases) page.
+
+## [0.2.26] - 2026-09-16
+
+### Added
+- npm / stars badges, star CTA and `llms.txt` for agent discovery
+- Cross-link to companion tool `cssgraph`
+
+See [releases](https://github.com/mack-peng/cssprobe-cli/releases) for the complete history.

package/README.md

@@ -2,7 +2,9 @@
 
 Runtime CSS probe — inspect layout, scroll, colors, backgrounds, fonts and more in a live browser. Built for both humans and AI agents.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.5.0-brightgreen.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.5.0-brightgreen.svg)](https://nodejs.org/) [![npm version](https://img.shields.io/npm/v/cssprobe-cli.svg)](https://www.npmjs.com/package/cssprobe-cli) [![npm downloads](https://img.shields.io/npm/dm/cssprobe-cli.svg)](https://www.npmjs.com/package/cssprobe-cli) [![GitHub stars](https://img.shields.io/github/stars/mack-peng/cssprobe-cli?style=social)](https://github.com/mack-peng/cssprobe-cli/stargazers)
+
+> Static + runtime CSS diagnosis for AI agents — pair with [cssgraph](https://github.com/mack-peng/cssgraph) (the CSS knowledge graph) for the full picture.
 
 ---
 
@@ -104,7 +106,7 @@ cssprobe-cli open https://mysite.com --headed
 # User manually logs in...
 
 # Save session state for future use
-cssprobe-cli playwright "page.context().storageState({path: 'state.json'})"
+cssprobe-cli state-save --name mysite
 
 # Reopen with saved state (no login needed)
 cssprobe-cli open https://mysite.com --state state.json --headed
@@ -158,13 +160,14 @@ cssprobe-cli inspect body --json | jq '.findings[] | {id, confidence, message}'
 | `resize <width> <height>` | Resize browser viewport |
 | `eval <expression>` | Evaluate JavaScript (browser context) |
 | `playwright <call>` | Execute Playwright API (Node.js context) |
-| `screenshot` | Take screenshot |
+| `screenshot` | Take screenshot (saves to ~/.cssprobe-cli/screenshots/, --out to override) |
 
 ### State
 
 | Command | Description |
 |---------|-------------|
 | `state-import <file>` | Import cookies from Netscape format |
+| `state-save` | Save current browser session state (cookies + localStorage) |
 
 ### Configuration
 
@@ -193,6 +196,34 @@ The report header shows: `confidence: DEFINITE 8 | INDEFINITE 0 | UNVERIFIABLE 1
 
 ---
 
+## Complementary Tool: cssgraph
+
+cssprobe-cli is a **runtime** CSS probe — it opens a real browser and reads what is actually rendered. For **static** questions about the source code — where is `.btn-primary` defined, what cascades over it, which components reference it, what would change if I edited it — use [cssgraph](https://github.com/mack-peng/cssgraph), a local SQLite knowledge graph of every className, property, variable, and at-rule in your stylesheets. The two tools complement each other:
+
+| | cssgraph (static) | cssprobe-cli (runtime) |
+|---|---|---|
+| Analyzes | source code (CSS/SCSS/Less + JSX/TSX + templates) | live browser (computed styles + DOM) |
+| Answers | where a class is defined, cascade, impact, unused CSS | actual rendered layout, overflow, scroll, height chains |
+| When | before/without a browser | after static analysis, to verify at runtime |
+| Usage | `cssgraph init` + `explore`/`rule`/`impact` | `open` + `inspect`/`layout`/`findings` |
+
+**Recommended workflow for a style problem** — go static first, then verify at runtime:
+
+```bash
+# 1. Static: find the definitions, cascade, and blast radius (cssgraph)
+cssgraph explore .btn-primary
+cssgraph cascade .btn-primary
+
+# 2. Runtime: confirm what actually renders (cssprobe-cli)
+cssprobe-cli open https://example.com
+cssprobe-cli inspect .btn-primary
+cssprobe-cli findings .btn-primary
+```
+
+Install: `npm install -g cssgraph` (requires Node.js >= 22.5.0). It exposes 12 MCP tools (`cssgraph_explore`, `cssgraph_rule`, `cssgraph_impact`, …) plus CLI commands. See [npm](https://www.npmjs.com/package/cssgraph) / [GitHub](https://github.com/mack-peng/cssgraph).
+
+---
+
 ## Configuration
 
 ```bash
@@ -240,6 +271,12 @@ npm test            # Run unit tests (58 tests)
 npx tsc --noEmit    # Type check only
 ```
 
+## If cssprobe-cli is useful
+
+A ⭐ star helps other developers discover it — and tells us to keep shipping.
+
+---
+
 ## License
 
 MIT

package/dist/cli/commands.js

@@ -129,6 +129,7 @@ const screenshot = (0, command_1.declareCommand)({
     description: 'Take a screenshot of the current page',
     options: z.object({
         'full-page': z.boolean().optional().describe('take screenshot of the full scrollable page'),
+        out: z.string().optional().describe('output file path (default: ~/.cssprobe-cli/screenshots/<timestamp>.png)'),
     }),
 });
 const resize = (0, command_1.declareCommand)({

package/dist/cli/program.js

@@ -298,12 +298,41 @@ async function handleSessionCommand(commandName, command, args, output) {
         if (args.json)
             runArgs.json = true;
         const result = await session.run(runArgs);
+        // Screenshot: save the base64 data URL to a file and report the path
+        if (commandName === 'screenshot' && typeof result.text === 'string' && result.text.startsWith('data:image/png;base64,')) {
+            const saved = saveScreenshotFile(result.text, parsed.out);
+            if (output.json) {
+                console.log(JSON.stringify({ saved }, null, 2));
+            }
+            else {
+                console.log(`Screenshot saved: ${saved}`);
+            }
+            return;
+        }
         console.log(result.text);
     }
     catch (e) {
         output.error(e instanceof Error ? e.message : String(e));
     }
 }
+function saveScreenshotFile(dataUrl, out) {
+    const base64 = dataUrl.replace(/^data:image\/png;base64,/, '');
+    const buffer = Buffer.from(base64, 'base64');
+    const resolvedOut = out
+        ? path_1.default.resolve(out)
+        : (() => {
+            const dir = path_1.default.join(os_1.default.homedir(), '.cssprobe-cli', 'screenshots');
+            if (!fs_1.default.existsSync(dir))
+                fs_1.default.mkdirSync(dir, { recursive: true });
+            const ts = new Date().toISOString().replace(/[:.]/g, '-');
+            return path_1.default.join(dir, `screenshot-${ts}.png`);
+        })();
+    const dir = path_1.default.dirname(resolvedOut);
+    if (!fs_1.default.existsSync(dir))
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    fs_1.default.writeFileSync(resolvedOut, buffer);
+    return resolvedOut;
+}
 // ── config commands ──
 function handleConfigCommands(commandName, command, args, output) {
     try {

package/dist/collector-bundle.js

@@ -124,8 +124,8 @@ var __cssprobe_cli = (() => {
       } catch (_e) {
         accessible = false;
         crossOriginBlocked.count++;
-        const short = (sheet.href || "unknown").split("/").pop() || "unknown";
-        if (!blockedSheetUrls.includes(short)) blockedSheetUrls.push(short);
+        const href = (sheet.href || "unknown").replace(/^https?:\/\//, "");
+        if (!blockedSheetUrls.includes(href)) blockedSheetUrls.push(href);
         continue;
       }
       if (!rules) continue;

package/dist/daemon/daemon.js

@@ -174,6 +174,10 @@ async function executeCommand(launcher, args) {
             if (!page)
                 throw new Error('Browser is not open. Run: cssprobe-cli open <url>');
             const result = await page.evaluate(expression);
+            if (typeof result === 'string')
+                return { text: result };
+            if (result === undefined)
+                return { text: 'undefined' };
             return { text: JSON.stringify(result, null, 2) };
         }
         case 'resize': {
@@ -198,6 +202,8 @@ async function executeCommand(launcher, args) {
             const asyncFunction = new AsyncFunction('page', 'browser', `return ${call}`);
             const browser = page.context().browser();
             const result = await asyncFunction(page, browser);
+            if (result === undefined)
+                return { text: JSON.stringify({ ok: true, value: null, note: 'call returned no value' }) };
             return { text: JSON.stringify(result, null, 2) };
         }
         case 'state-save': {

package/dist/engine/collector.js

@@ -38,9 +38,9 @@ function matchDeclarations(el, wantedProps, crossOriginBlocked, blockedSheetUrls
         catch (_e) {
             accessible = false;
             crossOriginBlocked.count++;
-            const short = (sheet.href || 'unknown').split('/').pop() || 'unknown';
-            if (!blockedSheetUrls.includes(short))
-                blockedSheetUrls.push(short);
+            const href = (sheet.href || 'unknown').replace(/^https?:\/\//, '');
+            if (!blockedSheetUrls.includes(href))
+                blockedSheetUrls.push(href);
             continue;
         }
         if (!rules)

package/dist/engine/renderer.js

@@ -53,9 +53,9 @@ function renderMarkdown(snapshot, findings, brief = false, layout = false) {
     if (snapshot.crossOriginBlocked && snapshot.crossOriginBlocked > 0) {
         lines.push('');
         lines.push('## Cross-origin limitation');
-        lines.push(`\u26A0 ${snapshot.crossOriginBlocked} stylesheet(s) blocked by browser security (SecurityError). Declared values from these sheets are marked UNVERIFIABLE \u2014 computed values from getComputedStyle() are still accurate.`);
+        lines.push(`\u26A0 ${snapshot.crossOriginBlocked} stylesheet(s) from CDN/cross-origin were blocked by browser security (SecurityError). Declared values from these sheets are marked UNVERIFIABLE \u2014 computed styles from getComputedStyle() are still accurate.`);
         if (snapshot.blockedSheetUrls && snapshot.blockedSheetUrls.length > 0) {
-            lines.push(`Blocked: ${snapshot.blockedSheetUrls.join(', ')}`);
+            lines.push(`Blocked (from CDN/cross-origin): ${snapshot.blockedSheetUrls.join(', ')}`);
         }
     }
     return lines.join('\n');

package/dist/help.json

@@ -90,9 +90,10 @@
       ]
     },
     "screenshot": {
-      "help": "cssprobe-cli screenshot \n\nTake a screenshot of the current page\n\nOptions:\n  --full-page                 take screenshot of the full scrollable page\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli screenshot \n\nTake a screenshot of the current page\n\nOptions:\n  --full-page                 take screenshot of the full scrollable page\n  --out                       output file path (default: ~/.cssprobe-cli/screenshots/<timestamp>.png)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
-        "full-page": "boolean"
+        "full-page": "boolean",
+        "out": "string"
       },
       "args": []
     },

package/docs/code-design-session-mode.md

@@ -387,7 +387,8 @@ CLI 输出: {"success":true}
 
 | 旧命令 | 新命令 | 说明 |
 |--------|--------|------|
-| `login <url>` | `open <url>` → 手动登录 → `save-state` | 流程变化 |
+| `login <url>` | `open <url>` → 手动登录 → `state-save` | 流程变化 |
 | `inspect <url> --wait` | `open <url>` → 手动操作 → `inspect <selector>` | 流程变化 |
 | `interactive <url>` | `open <url>` → 多次 `inspect`/`tree`/`inject-css` | 流程变化 |
 | `state-import` | 保留 | 不变 |
+| `state-save` | 新增 | 保存当前会话 cookies + localStorage |

package/docs/guide/installation.md

@@ -88,7 +88,7 @@ cssprobe-cli inspect https://getbootstrap.com/docs/5.3/examples/checkout body --
 
 ## Step 4: Login-Protected Pages
 
-Many pages require authentication. cssprobe-cli supports three approaches:
+Many pages require authentication. cssprobe-cli supports these approaches:
 
 ### Option A: Import Cookies from Browser Export
 
@@ -114,13 +114,26 @@ cssprobe-cli open https://mysite.com --headed
 cssprobe-cli inspect .target
 ```
 
-### Option C: Merge Cookies into Existing State
+### Option C: Interactive Login + Save State (recommended for reuse)
+
+```bash
+cssprobe-cli open https://mysite.com --headed
+# Browser opens -> complete login manually
+cssprobe-cli state-save --name mysite
+# Saves to ~/.cssprobe-cli/states/mysite.json
+
+# Later, reuse the saved state
+cssprobe-cli open https://mysite.com --state ~/.cssprobe-cli/states/mysite.json
+cssprobe-cli inspect .target
+```
+
+### Option D: Merge Cookies into Existing State
 
 ```bash
 cssprobe-cli state-import new-cookies.txt --merge existing-state.json --out updated.json
 ```
 
-### Option D: Open with Saved State
+### Option E: Open with Saved State
 
 ```bash
 # Import cookies first
@@ -217,10 +230,10 @@ confidence: DEFINITE 8 | INDEFINITE 0 | UNVERIFIABLE 1
 → Run `npm run build` in the cssprobe-cli project directory.
 
 **Cross-origin stylesheet blocked**
-→ This is expected. Declared values from blocked sheets are marked UNVERIFIABLE. Computed values from getComputedStyle() are still accurate.
+→ This is expected. The report lists blocked stylesheet URLs (from CDN/cross-origin) with full paths. Declared values from those sheets are marked UNVERIFIABLE, but computed values from getComputedStyle() are still accurate.
 
 **Page needs login**
-→ Use `cssprobe-cli open <url> --headed` for interactive login, or `cssprobe-cli state-import cookies.txt --name mysite` to import cookies.
+→ Use `cssprobe-cli open <url> --headed` for interactive login, then `cssprobe-cli state-save --name mysite` to save the session, or `cssprobe-cli state-import cookies.txt --name mysite` to import cookies.
 
 ---
 
@@ -251,6 +264,33 @@ npm install -g cssprobe-cli && npx playwright install chromium && cssprobe-cli i
 
 ---
 
+## Complementary Tool: cssgraph
+
+cssprobe-cli answers **runtime** questions — what a page actually renders. For **static** questions about the source — where a class is defined, what cascades over it, which components reference it, what a change would affect — install [cssgraph](https://github.com/mack-peng/cssgraph). It builds a local SQLite knowledge graph of every className, property, variable, and at-rule from your stylesheets (CSS/SCSS/Less + JSX/TSX + templates), 100% local.
+
+```bash
+npm install -g cssgraph        # requires Node.js >= 22.5.0
+cd your-project
+cssgraph init                  # build the knowledge graph
+```
+
+**Work together — static first, runtime to verify:**
+
+```bash
+# 1. Static (cssgraph): locate definitions, cascade, impact
+cssgraph explore .modal
+cssgraph rule ".modal > .content"
+
+# 2. Runtime (cssprobe-cli): confirm actual rendering
+cssprobe-cli open https://example.com
+cssprobe-cli inspect .modal
+cssprobe-cli findings .modal
+```
+
+cssgraph also ships an MCP server with 12 tools (`cssgraph_explore`, `cssgraph_callers`, `cssgraph_impact`, `cssgraph_rule`, …) so an agent can answer static CSS questions in one call. See [npm](https://www.npmjs.com/package/cssgraph) / [GitHub](https://github.com/mack-peng/cssgraph).
+
+---
+
 ## Done
 
 You now have programmatic control over CSS inspection. Analyze layout, detect overflow, check scroll behavior, verify anchors — all from a terminal an agent can automate.

package/llms.txt

@@ -0,0 +1,14 @@
+# cssprobe-cli
+
+> Runtime CSS probe — inspect layout, scroll, colors, backgrounds, fonts in a live browser. Returns DOM tree, ASCII layout diagram and confidence-classified findings for humans and AI agents.
+
+## Documentation
+
+- [README](https://raw.githubusercontent.com/mack-peng/cssprobe-cli/main/README.md): overview, quick start, configuration
+- [Installation guide](https://raw.githubusercontent.com/mack-peng/cssprobe-cli/main/docs/guide/installation.md): agent-friendly install and skill wiring (Claude Code, Cursor, Codex, …)
+- [npm package](https://www.npmjs.com/package/cssprobe-cli): `npm install -g cssprobe-cli`
+
+## Optional
+
+- [GitHub repository](https://github.com/mack-peng/cssprobe-cli): source code, issues, releases
+- [cssgraph](https://github.com/mack-peng/cssgraph): companion static CSS knowledge graph for AI agents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssprobe-cli",
-  "version": "0.2.24",
+  "version": "0.2.26",
   "description": "Runtime CSS probe — inspect layout, colors, backgrounds, fonts and more in a live browser. AI agents and shell automation.",
   "keywords": [
     "css",
@@ -30,7 +30,9 @@
     "docs",
     "README.md",
     "LICENSE",
-    "AGENTS.md"
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "llms.txt"
   ],
   "engines": {
     "node": ">=18"