cssprobe-cli 0.2.5 → 0.2.7

package/AGENTS.md

@@ -2,9 +2,9 @@
 
 ## Project
 
-`cssprobe-cli` — Runtime CSS probe for layout/scroll/overflow/color/font inspection. Entrypoint: `bin/cssprobe-cli.js` → `require('../dist/index')`.
-Build: `npm run build` (= `tsc` + `esbuild` collector IIFE bundle + `tsx scripts/generate-help.ts`).
-Test: `npm test` (= `tsx --test tests/*.test.ts` — Node.js built-in test runner, 26 tests).
+`cssprobe-cli` — Runtime CSS probe for layout/scroll/overflow/color/font inspection with session-based browser management. Entrypoint: `bin/cssprobe-cli.js` → `require('../dist/index')`.
+Build: `npm run build` (= `tsc` + `esbuild` collector IIFE bundle + `esbuild` daemon entry + `tsx scripts/generate-help.ts`).
+Test: `npm test` (= `tsx --test tests/*.test.ts` — Node.js built-in test runner, 45 tests).
 Dependencies: `playwright-core`, `zod`. Dev: `typescript`, `@types/node`, `tsx`, `esbuild`.
 
 ## Architecture
@@ -13,36 +13,73 @@ Dependencies: `playwright-core`, `zod`. Dev: `typescript`, `@types/node`, `tsx`,
 src/
 ├── index.ts                   # export { program } from './cli/program'
 ├── cli/
-│   ├── program.ts             # Entry: minimist parse → dispatch → engine call
-│   ├── commands.ts            # 10 command definitions — all Zod schemas
+│   ├── program.ts             # Entry: minimist parse → session command dispatch
+│   ├── commands.ts            # Command definitions — all Zod schemas
 │   ├── command.ts             # declareCommand(), parseCommand() (Zod validation)
 │   ├── output.ts              # TextOutput / JsonOutput strategy pattern
 │   └── minimist.ts            # Arguments parser (forked from playwright-cli)
+├── daemon/
+│   ├── session.ts             # Session management (single session, Unix socket)
+│   ├── daemon.ts              # Daemon process: browser lifecycle + command execution
+│   └── daemonEntry.ts         # Daemon entry point (spawned as child process)
 ├── engine/
 │   ├── types.ts               # Shared types: Snapshot, TreeNode, Finding, Confidence
 │   ├── collector.ts           # Browser-side: DOM traversal, computed styles, declared values
 │   ├── analyzer.ts            # Node-side: pure functions, confidence model, pattern detection
 │   └── renderer.ts            # Markdown / JSON rendering
 ├── browser/
-│   └── launcher.ts            # Playwright wrapper: launch, navigate, inject collector, state loading
-└── config/
-    ├── config.ts              # Config loader (CLI → env → ~/.cssprobe-clirc profiles)
-    └── helpGenerator.ts       # Build-time: Zod schemas → dist/help.json
+│   └── launcher.ts            # Playwright wrapper: launch, navigate, inject collector
+├── config/
+│   ├── config.ts              # Config loader (CLI → env → ~/.cssprobe-clirc profiles)
+│   └── helpGenerator.ts       # Build-time: Zod schemas → dist/help.json
+└── utils/
+    └── socketConnection.ts    # Socket communication (adapted from playwright-cli)
 ```
 
 ## Key Patterns
 
+- **Session-based architecture**: Inspired by playwright-cli. `open` starts a daemon process, subsequent commands connect via Unix socket. Single session (default) mode.
+- **Daemon process**: Long-running background process that manages the browser and executes commands. Communicates via Unix domain socket.
 - **Three-layer engine**: `collector.ts` (browser, esbuild IIFE) → `analyzer.ts` (Node, pure functions) → `renderer.ts` (Markdown/JSON). Collector only gathers facts; analyzer does inference with confidence; renderer formats output.
 - **Collector bundling**: `collector.ts` is bundled by esbuild as an IIFE (`format: 'iife', globalName: '__cssprobe-cli'`). The launcher injects it via `page.addScriptTag({ content })`, then calls `window.__cssprobe-cli.collect(cfg)`.
 - **Confidence model**: Every `Finding` carries `confidence: 'DEFINITE' | 'INDEFINITE' | 'UNVERIFIABLE'`. Computed values = DEFINITE. Percent declarations = INDEFINITE. Missing/blocked declarations = UNVERIFIABLE.
 - **Command definition**: `declareCommand({ name, category, description, args?, options? })` — purely declarative, no execution logic.
-- **Command dispatch**: `minimist` parse → `parseCommand()` Zod validate → `switch(commandName)` → handler function.
+- **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 <file>` loads Playwright storage state (cookies + localStorage). `state-import` converts Netscape cookies. `login` does interactive login + save state.
+- **State management**: `state-import` converts Netscape cookies. 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)`
 
+## Commands
+
+### Session Management
+- `open [url]` — Open browser in session mode (non-blocking)
+- `close` — Close the browser session
+- `status` — Show current session status
+
+### CSS Inspection
+- `inspect <selector>` — Inspect runtime CSS of a page element
+- `tree <selector>` — Show DOM tree structure
+- `layout <selector>` — Show ASCII layout diagram
+- `findings <selector>` — Show only issues/warnings/errors
+
+### CSS Injection
+- `inject-css <css>` — Inject CSS into the current page
+
+### Browser
+- `screenshot` — Take a screenshot
+- `eval <expression>` — Evaluate JavaScript
+
+### State
+- `state-import [file]` — Import cookies from Netscape format
+
+### Config
+- `config-show` / `config-set` / `config-list` / `config-use` / `config-new` / `config-path`
+
+### Skills
+- `skill-install` / `skill-uninstall`
+
 ## Adding a Command
 
 1. Add `declareCommand({...})` in `src/cli/commands.ts` following the existing pattern
@@ -57,11 +94,42 @@ src/
 npm run build
 ├── 1. tsc                    # Compile TS → dist/ (includes .d.ts)
 ├── 2. esbuild collector.ts   # Bundle browser-side code → dist/collector-bundle.js (IIFE)
-└── 3. tsx generate-help.ts   # Zod schemas → dist/help.json
+├── 3. esbuild daemonEntry.ts # Bundle daemon entry → dist/daemonEntry.js (CJS)
+└── 4. tsx generate-help.ts   # Zod schemas → dist/help.json
 ```
 
 The collector bundle is a self-contained IIFE that exposes `window.__cssprobe-cli.collect(cfg)`. It runs entirely in the browser context — no Node imports.
 
+## Session Mode
+
+cssprobe-cli uses a session-based architecture inspired by playwright-cli:
+
+```bash
+# Open browser (starts daemon, non-blocking)
+cssprobe-cli open https://example.com
+
+# User operates manually in the browser...
+
+# Run CSS diagnosis
+cssprobe-cli inspect .sidebar --json
+cssprobe-cli tree .content --depth 3
+cssprobe-cli layout .header
+
+# Inject CSS to test changes
+cssprobe-cli inject-css ".sidebar { background: red; }"
+
+# Close browser (stops daemon)
+cssprobe-cli close
+```
+
+### How It Works
+
+1. `open` spawns a daemon process that manages the browser
+2. Daemon listens on a Unix socket at `~/Library/Caches/cssprobe-cli/daemon/<hash>/default.sock`
+3. Subsequent commands connect to the socket and send commands
+4. Daemon executes commands using Playwright's browser API
+5. `close` stops the daemon and closes the browser
+
 ## What Makes This Different from dom-report
 
 | | dom-report (old) | cssprobe-cli (new) |
@@ -72,6 +140,6 @@ The collector bundle is a self-contained IIFE that exposes `window.__cssprobe-cl
 | Output | Single markdown string | Markdown (default) / JSON (--json) |
 | Config | `window.__DOM_REPORT_CFG` global + eval two-step | CLI flags → env → rc file, one command |
 | ROOT_SELECTOR | Manual or eval probe | `--auto-root` auto-detection |
-| Tests | None | 26 unit tests (command, analyzer, output) |
-| Build | Regex stripping CJS module.exports | esbuild IIFE bundle, clean build |
-| Auth | None | `--state`, `login`, `state-import` |
+| Tests | None | 45 unit tests (command, analyzer, output, renderer) |
+| Build | Regex stripping CJS module.exports | esbuild IIFE + CJS bundle, clean build |
+| Session | None (blocking commands) | Session-based daemon architecture |

package/README.md

@@ -23,100 +23,137 @@ cssprobe-cli skill-install
 ### 1. Inspect a Page
 
 ```bash
-# With explicit selector
-cssprobe-cli inspect https://getbootstrap.com/docs/5.3/examples/checkout ".container"
+# Open browser (non-blocking, starts daemon session)
+cssprobe-cli open https://getbootstrap.com/docs/5.3/examples/checkout
 
-# Auto-detect root element
-cssprobe-cli inspect https://getbootstrap.com/docs/5.3/examples/checkout
+# Inspect with CSS selector
+cssprobe-cli inspect .container
 
-# Local HTML file
-cssprobe-cli inspect ./test.html ".container"
+# Show DOM tree
+cssprobe-cli tree .container --depth 3
+
+# Show ASCII layout diagram
+cssprobe-cli layout .container
+
+# Show only issues/warnings
+cssprobe-cli findings .container
+
+# Close browser when done
+cssprobe-cli close
 ```
 
 ### 2. Login-Protected Pages
 
 ```bash
-# Import cookies from browser export (Netscape format)
-cssprobe-cli state-import cookies.txt --out ~/.cssprobe-cli/states/mysite.json
+# Open browser in headed mode
+cssprobe-cli open https://mysite.com --headed
 
-# Or interactive login
-cssprobe-cli login https://mysite.com
+# User manually logs in...
 
-# Then inspect with state
-cssprobe-cli inspect https://mysite.com/page ".target" --state ~/.cssprobe-cli/states/mysite.json
+# Run diagnosis on authenticated page
+cssprobe-cli inspect .dashboard
 
-# Wait for user interaction before collecting (e.g. click a button to open a dialog)
-cssprobe-cli inspect https://mysite.com/page ".dialog" --state ~/.cssprobe-cli/states/mysite.json --wait
-```
+# Inject CSS to test changes
+cssprobe-cli inject-css ".sidebar { background: #f0f0f0; }"
 
-### 3. Interactive Mode
+# Take screenshot
+cssprobe-cli screenshot
 
-```bash
-# Open browser and inspect interactively (REPL mode)
-cssprobe-cli interactive https://mysite.com --state ~/.cssprobe-cli/states/mysite.json
+# Close when done
+cssprobe-cli close
 ```
 
-Runtime commands:
-```
-inspect> tree .dialog-A               # DOM tree
-inspect> layout .sidebar-B            # ASCII layout diagram
-inspect> sketch .content              # Tree sketch (issues only)
-inspect> findings .modal              # Findings only
-inspect> json .dialog-A               # JSON output
-inspect> report .dialog-A             # Full report
-inspect> .dialog-A                    # Shorthand for report
-inspect> navigate https://other.com   # Navigate to new URL
-inspect> depth 10                     # Set depth
-inspect> help                         # Show help
-inspect> quit                         # Exit
+### 3. Import Cookies
+
+```bash
+# Import cookies from browser export (Netscape format)
+cssprobe-cli state-import cookies.txt --out ~/.cssprobe-cli/states/mysite.json
 ```
 
 ### 4. JSON Output
 
 ```bash
-cssprobe-cli inspect https://getbootstrap.com/docs/5.3/examples/checkout body --json
-cssprobe-cli inspect https://getbootstrap.com/docs/5.3/examples/checkout body --json | jq '.findings[] | {id, confidence, message}'
+cssprobe-cli open https://getbootstrap.com/docs/5.3/examples/checkout
+cssprobe-cli inspect body --json
+cssprobe-cli inspect body --json | jq '.findings[] | {id, confidence, message}'
+cssprobe-cli close
 ```
 
 ---
 
-## Output Modes
+## Session Mode
 
-| Flag | Output | Use Case |
-|------|--------|----------|
-| (default) | Markdown report with ancestor chain, DOM tree, findings | Terminal viewing |
-| `--json` | Structured JSON with snapshot, findings, confidence summary | Scripts, `jq` pipes, AI agent consumption |
-| `--brief` | Compact output: tree sketch + warnings/errors only | Quick overview |
-| `--layout` | ASCII layout diagram showing element positions and sizes | Visual layout inspection |
+cssprobe-cli uses a session-based architecture for non-browser interaction:
+
+```bash
+# Start session (opens browser, returns immediately)
+cssprobe-cli open <url>
+
+# Run commands (each command is independent, non-blocking)
+cssprobe-cli inspect <selector>
+cssprobe-cli tree <selector>
+cssprobe-cli layout <selector>
+cssprobe-cli findings <selector>
+cssprobe-cli inject-css <css>
+cssprobe-cli screenshot
+cssprobe-cli eval <expression>
+
+# Check session status
+cssprobe-cli status
+
+# End session (closes browser)
+cssprobe-cli close
+```
 
 ---
 
 ## Commands
 
-### Inspection
+### Session Management
+
+```bash
+cssprobe-cli open [url]           # Open browser in session mode (non-blocking)
+cssprobe-cli close                # Close browser session
+cssprobe-cli status               # Show session status
+```
+
+### CSS Inspection
+
+```bash
+cssprobe-cli inspect <selector>   # Full CSS diagnosis
+cssprobe-cli tree <selector>      # DOM tree structure
+cssprobe-cli layout <selector>    # ASCII layout diagram
+cssprobe-cli findings <selector>  # Only issues/warnings/errors
+```
+
+### CSS Injection
 
 ```bash
-cssprobe-cli inspect <url> [selector]    # Inspect CSS layout
-cssprobe-cli interactive <url>           # Interactive REPL mode
-cssprobe-cli login <url>                 # Interactive login, save state
-cssprobe-cli state-import [file]         # Import cookies from Netscape format
+cssprobe-cli inject-css <css>     # Inject CSS into current page
 ```
 
-### Inspection
+### Browser
 
 ```bash
-cssprobe-cli inspect https://getbootstrap.com/docs/5.3/examples/checkout body
+cssprobe-cli screenshot           # Take screenshot
+cssprobe-cli eval <expression>    # Evaluate JavaScript
+```
+
+### State
+
+```bash
+cssprobe-cli state-import [file]  # Import cookies from Netscape format
 ```
 
 ### Configuration
 
 ```bash
-cssprobe-cli config-show                 # Show current config
-cssprobe-cli config-set <key> <value>    # Set config value
-cssprobe-cli config-list                 # List all profiles
-cssprobe-cli config-use <name>           # Switch active profile
-cssprobe-cli config-new <name>           # Create new profile
-cssprobe-cli config-path                 # Show config file path
+cssprobe-cli config-show          # Show current config
+cssprobe-cli config-set <key> <value>  # Set config value
+cssprobe-cli config-list          # List all profiles
+cssprobe-cli config-use <name>    # Switch active profile
+cssprobe-cli config-new <name>    # Create new profile
+cssprobe-cli config-path          # Show config file path
 ```
 
 ---
@@ -124,24 +161,41 @@ cssprobe-cli config-path                 # Show config file path
 ## inspect Options
 
 ```bash
-cssprobe-cli inspect <url> [selector] [options]
+cssprobe-cli inspect <selector> [options]
 
 Arguments:
-  <url>                       URL, file:// path, or local HTML file
-  [selector]                  CSS selector for root (auto-detected if omitted)
+  <selector>                  CSS selector for root element
 
 Options:
   --json                      Output structured JSON
-  --headed                    Show browser window
-  --browser <engine>          chromium|firefox|webkit (default chromium)
-  --zoom                      Run 1x/0.5x viewport diagnosis
-  --depth <n>                 DOM tree depth (default: auto)
-  --max-nodes <n>             Node count cap (default 60)
-  --up-to <tag>               Ancestor stop tag (default html)
-  --state <file>              Load saved state (cookies + localStorage)
   --brief                     Compact output: tree sketch + warnings/errors only
-  --layout                    ASCII layout diagram showing element positions and sizes
-  --wait                      Wait for user interaction before collecting (implies --headed)
+  --layout                    ASCII layout diagram
+  --depth <n>                 DOM tree depth (default: auto, max 20)
+```
+
+---
+
+## tree Options
+
+```bash
+cssprobe-cli tree <selector> [options]
+
+Arguments:
+  <selector>                  CSS selector for root element
+
+Options:
+  --depth <n>                 Tree depth (default: auto, max 20)
+```
+
+---
+
+## inject-css
+
+```bash
+cssprobe-cli inject-css <css>
+
+Arguments:
+  <css>                       CSS code to inject into the current page
 ```
 
 ---
@@ -189,6 +243,7 @@ The report header shows: `confidence: DEFINITE 8 | INDEFINITE 0 | UNVERIFIABLE 1
 # Set values
 cssprobe-cli config-set browser chromium
 cssprobe-cli config-set depth 8
+cssprobe-cli config-set viewport 375x812
 
 # Show current config
 cssprobe-cli config-show
@@ -206,6 +261,7 @@ Priority: CLI flags > Environment variables > Config file
 --browser       CSSPROBE_BROWSER
 --depth         CSSPROBE_DEPTH
 --headed        CSSPROBE_HEADED
+--viewport      CSSPROBE_VIEWPORT
 -p, --profile   CSSPROBE_PROFILE
 ```
 
@@ -245,8 +301,8 @@ cssprobe-cli skill-uninstall
 
 ```bash
 npm install
-npm run build       # tsc + esbuild collector bundle + generate help.json
-npm test            # Run unit tests
+npm run build       # tsc + esbuild collector + daemon entry + generate help.json
+npm test            # Run unit tests (45 tests)
 npx tsc --noEmit    # Type check only
 ```
 

package/dist/browser/launcher.d.ts

@@ -1,9 +1,15 @@
+import { type Page } from 'playwright-core';
 import type { Snapshot, CollectConfig } from '../engine/types';
 export interface LauncherOptions {
     browser?: string;
     headed?: boolean;
     /** Path to a Playwright storage state file (cookies + localStorage). */
     state?: string;
+    /** Custom viewport size. Defaults to 1280×720. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
 }
 export declare class BrowserLauncher {
     private options;
@@ -27,5 +33,7 @@ export declare class BrowserLauncher {
      * Returns the path to the saved state file.
      */
     loginAndSave(url: string, statePath: string): Promise<string>;
+    /** Get the current page object. */
+    getPage(): Page | null;
     close(): Promise<void>;
 }

package/dist/browser/launcher.js

@@ -75,7 +75,8 @@ class BrowserLauncher {
         }
         this.browser = await factory.launch(launchOptions);
         // Load saved state if provided
-        const contextOptions = { viewport: { width: 1280, height: 720 } };
+        const vp = this.options.viewport || { width: 1280, height: 720 };
+        const contextOptions = { viewport: vp };
         if (this.options.state && fs_1.default.existsSync(this.options.state)) {
             contextOptions.storageState = this.options.state;
         }
@@ -212,7 +213,8 @@ class BrowserLauncher {
         if (execPath)
             launchOptions.executablePath = execPath;
         this.browser = await factory.launch(launchOptions);
-        this.context = await this.browser.newContext({ viewport: { width: 1280, height: 720 } });
+        const vp = this.options.viewport || { width: 1280, height: 720 };
+        this.context = await this.browser.newContext({ viewport: vp });
         this.page = await this.context.newPage();
         // Navigate to the target URL
         if (url.startsWith('http://') || url.startsWith('https://')) {
@@ -245,6 +247,10 @@ class BrowserLauncher {
         console.error(`  State saved to: ${resolvedPath}`);
         return resolvedPath;
     }
+    /** Get the current page object. */
+    getPage() {
+        return this.page;
+    }
     async close() {
         if (this.context)
             await this.context.close().catch(() => { });

package/dist/cli/command.d.ts

@@ -1,6 +1,6 @@
 import * as z from 'zod';
 import type zodType from 'zod';
-export type Category = 'core' | 'config' | 'skill';
+export type Category = 'core' | 'config' | 'skill' | 'cssprobe' | 'export';
 export interface HelpEntry {
     help: string;
     flags: Record<string, 'boolean' | 'string'>;

package/dist/cli/commands.d.ts

@@ -4,48 +4,24 @@ export declare const commands: {
     [k: string]: AnyCommandSchema;
 };
 export declare const inspectCommand: import("./command").CommandSchema<z.ZodObject<{
-    url: z.ZodString;
-    selector: z.ZodOptional<z.ZodString>;
+    selector: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    url: string;
-    selector?: string | undefined;
+    selector: string;
 }, {
-    url: string;
-    selector?: string | undefined;
+    selector: string;
 }>, z.ZodObject<{
     json: z.ZodOptional<z.ZodBoolean>;
-    headed: z.ZodOptional<z.ZodBoolean>;
-    browser: z.ZodOptional<z.ZodEnum<["chromium", "firefox", "webkit"]>>;
-    zoom: z.ZodOptional<z.ZodBoolean>;
-    depth: z.ZodOptional<z.ZodEffects<z.ZodNumber, number, unknown>>;
-    'max-nodes': z.ZodOptional<z.ZodEffects<z.ZodNumber, number, unknown>>;
-    'up-to': z.ZodOptional<z.ZodString>;
-    state: z.ZodOptional<z.ZodString>;
     brief: z.ZodOptional<z.ZodBoolean>;
     layout: z.ZodOptional<z.ZodBoolean>;
-    wait: z.ZodOptional<z.ZodBoolean>;
+    depth: z.ZodOptional<z.ZodEffects<z.ZodNumber, number, unknown>>;
 }, "strip", z.ZodTypeAny, {
     json?: boolean | undefined;
-    headed?: boolean | undefined;
-    browser?: "chromium" | "firefox" | "webkit" | undefined;
-    zoom?: boolean | undefined;
-    depth?: number | undefined;
-    'max-nodes'?: number | undefined;
-    'up-to'?: string | undefined;
-    state?: string | undefined;
     brief?: boolean | undefined;
     layout?: boolean | undefined;
-    wait?: boolean | undefined;
+    depth?: number | undefined;
 }, {
     json?: boolean | undefined;
-    headed?: boolean | undefined;
-    browser?: "chromium" | "firefox" | "webkit" | undefined;
-    zoom?: boolean | undefined;
-    depth?: unknown;
-    'max-nodes'?: unknown;
-    'up-to'?: string | undefined;
-    state?: string | undefined;
     brief?: boolean | undefined;
     layout?: boolean | undefined;
-    wait?: boolean | undefined;
+    depth?: unknown;
 }>>;