pinpoints 0.1.4

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2026 PinPoint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, merge, publish, distribute, and/or sublicense the Software,
+subject to the following conditions:
+
+1. The Software may be used for any purpose, including commercial applications.
+
+2. The Software may NOT be sold, rented, leased, or otherwise distributed for
+   a fee or any form of commercial compensation.
+
+3. The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# PinPoint — The missing link between your UI and your AI
+
+<p align="center"><img src="resources/icon.png" alt="PinPoint — UI Lens" width="160" /></p>
+
+**Pick UI elements and inject structured context directly into your AI coding agent** — without full-page screenshots.
+
+## Overview
+
+PinPoint is a VS Code extension that replaces the tedious "screenshot → paste → explain" workflow with instant, structured UI context capture. Hover over elements in a running web app, click to capture, and get AI-optimized context automatically injected into your chat.
+
+### Problem it solves
+
+Avoids noisy screenshots by providing structured, DOM-aware UI context that reduces ambiguity and token usage.
+
+### Solution
+
+Extracts stable selectors, cleaned element+parent HTML, layout bbox, and computed style diffs, optionally captures an element screenshot, and formats everything as AI-friendly Markdown.
+
+## Installation
+
+### 1) VS Code extension
+
+Install PinPoint from the VS Code Marketplace:
+
+https://marketplace.visualstudio.com/items?itemName=pinpointpoint.pinpoint
+
+### 2) Global CLI installation
+
+Install the CLI globally:
+
+```bash
+npm install -g pinpoints
+```
+
+Then run:
+
+```bash
+pinpoint start
+```
+
+
+
+## Usage
+
+### Quick Start
+
+1. **Start the picker**: Run command `PinPoint: Start Picker`
+2. **Enter URL**: Type the localhost or external URL to inspect
+3. **Hover & click**: Hover over elements in the browser; click to capture
+4. **Chat opens**: Formatted context is automatically injected
+5. **Add your instruction**: Type "Make this button look like..." and send
+
+
+
+
+## Capture Modes
+
+### Quick Fix (default)
+Minimal, fast capture for one-liner fixes.
+
+**Output:**
+```markdown
+## UI Element Context
+
+**URL:** http://localhost:3000
+**Selector:** `button[data-testid="submit"]`
+**Role:** button
+**Text:** "Submit Form"
+
+### Element Structure
+<button data-testid="submit" class="btn-primary">Submit Form</button>
+
+### Key Styles
+- display: block
+- padding: 12px 24px
+- background-color: #3b82f6
+
+### Layout
+- Position: absolute, top: 100px, left: 200px
+- Size: 120px × 40px
+
+---
+```
+
+### Layout
+Element + parent HTML + layout-critical styles.
+
+### CSS
+Computed style diff (what's explicitly set vs. inherited) + class list.
+
+### Visual
+Screenshot + bbox + minimal metadata.
+
+---
+
+## Architecture
+
+### Components
+
+**Extension Host** (`src/extension.ts`)
+- Commands, settings, status bar UI
+- Lifecycle management (cleanup on deactivate)
+
+**Browser Session Manager** (`src/browser/`)
+- Puppeteer-core Chrome launch with temp profile
+- Cleans up on exit (no profile pollution)
+
+**Extraction Pipeline** (`src/extraction/`)
+- `SelectorExtractor`: Robust selectors with confidence scoring
+- `DomExtractor`: Element + parent HTML (clean, truncated)
+- `StyleExtractor`: Computed styles + parent diff
+- `LayoutExtractor`: Bbox, viewport, scroll info
+- `ScreenshotExtractor`: Element screenshot via Puppeteer
+- `Redactor`: Truncates text, strips data URLs, removes event handlers
+
+**Schemas** (`src/schemas/`)
+- Zod-validated `MaxContext` (internal format)
+- Mode-specific exporters (QuickFix, Layout, CSS, Visual)
+
+**Chat Injection** (`src/export/`)
+- `ContextFormatter`: Markdown generation for AI agents
+- Direct VS Code chat input injection via `workbench.action.chat.open`
+
+**Picker Controller** (`src/picker/`)
+- Orchestrates extraction pipeline
+- Manages multi-element selection (Shift+click)
+- Handles temp file cleanup
+
+---
+
+## Technical Details
+
+### Browser Control
+- **Puppeteer-core** (CDP) for robust element selection
+- **Managed Chrome instance** (temp profile, auto-cleanup)
+- Overlay hover effect + click detection
+
+### Screenshots
+- **Element-level** via `elementHandle.screenshot()`
+- Saved to `.pinpoint/temp/element-<timestamp>.png`
+- Auto-referenced in chat via @ mention
+- Auto-deleted on extension close
+
+### Data Flow
+```
+Click element →
+  Extract selectors (robust priority order)
+  Extract DOM (element + parents, cleaned)
+  Extract styles (computed + parent diff)
+  Extract layout (bbox, viewport, scroll)
+  Optional: screenshot
+  Redact sensitive data (truncate, strip URLs)
+→ Format as markdown
+→ Inject to VS Code chat
+→ User adds instruction + sends
+```
+
+### Selector Priority
+1. `data-testid`, `data-test`, `data-qa` (explicit automation attributes)
+2. Non-UUID `id` (stable, semantic)
+3. `role` + unique `aria-label` (accessibility)
+4. Stable class combo (avoid utility classes)
+5. Position-based (nth-of-type) fallback
+
+### Style Diff
+Computes parent styles, keeps only layout-critical properties:
+- Display, position, dimensions (width, height)
+- Spacing (margin, padding)
+- Flexbox/Grid (flex-direction, justify-content, gap, etc.)
+- Overflow, z-index
+
+---
+
+
+## Troubleshooting
+
+### Chrome not found
+Make sure Chrome/Chromium is installed. On Windows, check `Program Files/Google/Chrome`. On macOS, check `/Applications/Google Chrome.app`.
+
+### Inspector gets stuck
+Press `Escape` to cancel, or run `PinPoint: Stop Picker`.
+
+### Screenshots not saving
+Check that `.pinpoint/temp/` is writable. The extension creates it automatically.
+
+### Selectors are unstable
+If you see UUIDs or random hashes in captured selectors, that's a sign the app doesn't use stable IDs. The picker falls back to position-based selectors, which may break if the DOM changes.

package/out/browser/browserSessionManager.d.ts

@@ -0,0 +1,19 @@
+import * as puppeteer from 'puppeteer-core';
+export interface BrowserSessionConfig {
+    headless?: boolean;
+    executablePath?: string;
+    url?: string;
+}
+export declare class BrowserSessionManager {
+    private browser;
+    private page;
+    private tempProfileDir;
+    launch(config?: BrowserSessionConfig): Promise<puppeteer.Page>;
+    private findChromeExecutable;
+    navigateTo(url: string): Promise<void>;
+    getPage(): puppeteer.Page | null;
+    getBrowser(): puppeteer.Browser | null;
+    close(): Promise<void>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=browserSessionManager.d.ts.map

package/out/browser/browserSessionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserSessionManager.d.ts","sourceRoot":"","sources":["../../src/browser/browserSessionManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAC;AAK5C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,IAAI,CAA+B;IAC3C,OAAO,CAAC,cAAc,CAAuB;IAEvC,MAAM,CAAC,MAAM,GAAE,oBAAyB,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC;IAiDxE,OAAO,CAAC,oBAAoB;IAkBtB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe5C,OAAO,IAAI,SAAS,CAAC,IAAI,GAAG,IAAI;IAIhC,UAAU,IAAI,SAAS,CAAC,OAAO,GAAG,IAAI;IAIhC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAuCtB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}

package/out/browser/browserSessionManager.js

@@ -0,0 +1,169 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserSessionManager = void 0;
+const puppeteer = __importStar(require("puppeteer-core"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+class BrowserSessionManager {
+    constructor() {
+        this.browser = null;
+        this.page = null;
+        this.tempProfileDir = null;
+    }
+    async launch(config = {}) {
+        try {
+            // Create temp profile directory
+            this.tempProfileDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pinpoint-'));
+            // Find Chrome executable
+            const executablePath = config.executablePath ||
+                this.findChromeExecutable();
+            if (!executablePath) {
+                throw new Error('Chrome/Chromium not found. Please install Chrome or specify executablePath.');
+            }
+            // Launch browser with temp profile
+            this.browser = await puppeteer.launch({
+                executablePath,
+                headless: false,
+                defaultViewport: null, // Use actual window size as viewport
+                userDataDir: this.tempProfileDir,
+                args: [
+                    '--disable-blink-features=AutomationControlled',
+                    '--disable-extensions',
+                    '--no-first-run',
+                    '--no-default-browser-check',
+                    '--start-maximized',
+                ],
+            });
+            // Use the default page that Chrome opens (avoids blank tab)
+            const pages = await this.browser.pages();
+            this.page = pages[0] || await this.browser.newPage();
+            // Navigate to URL if provided
+            if (config.url) {
+                await this.page.goto(config.url, {
+                    waitUntil: 'networkidle2',
+                    timeout: 30000,
+                });
+            }
+            return this.page;
+        }
+        catch (error) {
+            throw new Error(`Failed to launch browser: ${error}`);
+        }
+    }
+    findChromeExecutable() {
+        const possiblePaths = [
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', // macOS
+            '/usr/bin/google-chrome', // Linux
+            '/usr/bin/chromium-browser', // Linux
+            'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', // Windows
+            'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe', // Windows 32-bit
+        ];
+        for (const path of possiblePaths) {
+            if (fs.existsSync(path)) {
+                return path;
+            }
+        }
+        return null;
+    }
+    async navigateTo(url) {
+        if (!this.page) {
+            throw new Error('Page not initialized');
+        }
+        try {
+            await this.page.goto(url, {
+                waitUntil: 'networkidle2',
+                timeout: 30000,
+            });
+        }
+        catch (error) {
+            throw new Error(`Failed to navigate to ${url}: ${error}`);
+        }
+    }
+    getPage() {
+        return this.page;
+    }
+    getBrowser() {
+        return this.browser;
+    }
+    async close() {
+        if (this.page) {
+            try {
+                if (!this.page.isClosed()) {
+                    await this.page.close();
+                }
+            }
+            catch (error) {
+                console.error('Error closing page:', error);
+            }
+            finally {
+                this.page = null;
+            }
+        }
+        if (this.browser) {
+            try {
+                if (this.browser.connected) {
+                    await this.browser.close();
+                }
+            }
+            catch (error) {
+                console.error('Error closing browser:', error);
+            }
+            finally {
+                this.browser = null;
+            }
+        }
+        // Clean up temp directory
+        if (this.tempProfileDir) {
+            try {
+                if (fs.existsSync(this.tempProfileDir)) {
+                    fs.rmSync(this.tempProfileDir, { recursive: true, force: true });
+                }
+            }
+            catch (error) {
+                console.error('Error cleaning browser profile dir:', error);
+            }
+            finally {
+                this.tempProfileDir = null;
+            }
+        }
+    }
+    async dispose() {
+        await this.close();
+    }
+}
+exports.BrowserSessionManager = BrowserSessionManager;
+//# sourceMappingURL=browserSessionManager.js.map

package/out/browser/browserSessionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserSessionManager.js","sourceRoot":"","sources":["../../src/browser/browserSessionManager.ts"],"names":[],"mappings":"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"}

package/out/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/out/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}