@codewithdan/zingit 0.0.1

package/AGENTS.md

@@ -0,0 +1,214 @@
+# ZingIt - AI Agent Guide
+
+## Project Overview
+
+ZingIt is a browser-based annotation tool that allows users to click on webpage elements and add notes/instructions. These annotations are then sent to an AI agent (Claude Code or GitHub Copilot) which can automatically implement the requested changes.
+
+**Use case**: Point-and-click UI feedback that gets automatically implemented by AI.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        Browser                               │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                   ZingIt Client                      │    │
+│  │  (Lit Web Components injected via bookmarklet)       │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+└─────────────────────────┼───────────────────────────────────┘
+                          │ WebSocket
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    ZingIt Server                             │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
+│  │ WebSocket   │───▶│   Agent     │───▶│ Claude Code │     │
+│  │ Handler     │    │  Registry   │    │ or Copilot  │     │
+│  └─────────────┘    └─────────────┘    └─────────────┘     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Directory Structure
+
+```
+zingit/
+├── client/                    # Browser-side UI (Lit + Vite)
+│   ├── src/
+│   │   ├── components/        # Lit Web Components
+│   │   │   ├── zing-ui.ts     # Main orchestrator component
+│   │   │   ├── toolbar.ts     # Action buttons and status
+│   │   │   ├── highlight.ts   # Element hover highlight
+│   │   │   ├── markers.ts     # Numbered annotation badges
+│   │   │   ├── modal.ts       # Annotation input dialog
+│   │   │   ├── settings.ts    # Configuration panel
+│   │   │   ├── response.ts    # Agent response display
+│   │   │   ├── toast.ts       # Notification toasts
+│   │   │   └── help.ts        # Keyboard shortcuts overlay
+│   │   ├── services/
+│   │   │   ├── selector.ts    # CSS selector generation
+│   │   │   ├── storage.ts     # localStorage persistence
+│   │   │   └── websocket.ts   # WebSocket client with reconnection
+│   │   ├── utils/
+│   │   │   ├── geometry.ts    # Viewport/rect calculations
+│   │   │   └── markdown.ts    # Export formatting
+│   │   ├── types/index.ts     # TypeScript interfaces
+│   │   └── index.ts           # Entry point
+│   ├── index.html             # Dev page
+│   ├── products.html          # Test page
+│   ├── about.html             # Test page
+│   ├── contact.html           # Test page
+│   ├── styles.css             # Shared styles for test pages
+│   └── vite.config.ts         # Build config (IIFE for bookmarklet)
+│
+├── server/                    # Node.js WebSocket server
+│   └── src/
+│       ├── agents/
+│       │   ├── base.ts        # Abstract base agent class
+│       │   ├── claude.ts      # Claude Code CLI integration
+│       │   └── copilot.ts     # GitHub Copilot SDK integration
+│       ├── types.ts           # Server-side TypeScript interfaces
+│       └── index.ts           # WebSocket server entry point
+│
+└── AGENTS.md                  # This file
+```
+
+## Tech Stack
+
+### Client
+- **Lit 3.x** - Web Components framework
+- **TypeScript** - Strict mode enabled
+- **Vite** - Dev server and build tool
+- **Shadow DOM** - Style isolation (critical for bookmarklet injection)
+
+### Server
+- **Node.js** - Runtime
+- **ws** - WebSocket library
+- **tsx** - TypeScript execution
+- **@anthropic-ai/claude-agent-sdk** - Claude Code integration
+- **@github/copilot-sdk** - GitHub Copilot integration
+
+## Key Concepts
+
+### Annotations
+An annotation captures:
+- `selector` - CSS selector to locate the element
+- `identifier` - Human-readable element description (e.g., "button.primary")
+- `html` - Outer HTML of the element
+- `notes` - User's instructions for changes
+- `selectedText` - Any text the user had selected
+- `parentContext` - Parent element path for context
+- `textContent` - Plain text content
+
+### WebSocket Messages
+- **Client → Server**: `batch` (send annotations), `message` (follow-up), `reset` (clear session)
+- **Server → Client**: `connected`, `processing`, `delta` (streaming), `tool_start`/`tool_end`, `idle`, `error`
+
+### Agent System
+The server uses a pluggable agent architecture:
+- Set `AGENT=claude` or `AGENT=copilot` environment variable
+- Agents implement `Agent` interface with `createSession()` and `formatPrompt()`
+- Claude agent spawns `claude --print` CLI process
+- Copilot agent uses the GitHub Copilot SDK
+
+## Development Commands
+
+### Client
+```bash
+cd client
+npm install
+npm run dev          # Start Vite dev server (http://localhost:5200)
+npm run build        # Build for production (outputs IIFE bundle)
+npm run typecheck    # Type check without emitting
+npm run typecheck:watch  # Watch mode type checking
+```
+
+### Server
+```bash
+cd server
+npm install
+AGENT=claude npm run dev   # Start with Claude Code agent
+AGENT=copilot npm run dev  # Start with GitHub Copilot agent
+npm run typecheck          # Type check
+npm run typecheck:watch    # Watch mode type checking
+```
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `P` | Toggle annotation mode on/off |
+| `Ctrl/Cmd+Z` | Undo last annotation |
+| `?` | Show help overlay |
+| `` ` `` | Toggle ZingIt visibility |
+| `Esc` | Close current panel/modal |
+| `Ctrl/Cmd+Enter` | Save annotation (in modal) |
+
+## State Persistence
+
+The client persists state to `localStorage`:
+- `zingit_annotations` - Current page annotations (URL-scoped)
+- `zingit_settings` - User preferences (wsUrl, colors, projectDir)
+- `zingit_active` - Annotation mode on/off (persists across pages)
+
+## Important Implementation Details
+
+### Shadow DOM
+All components use Shadow DOM for style isolation. This is critical because ZingIt is injected as a bookmarklet into arbitrary pages - styles must not leak in or out.
+
+### Viewport Coordinates
+The highlight and marker positioning uses viewport coordinates (not page coordinates) because the main `zing-ui` component is `position: fixed`. Use `getElementViewportRect()` from `geometry.ts`.
+
+### WebSocket Reconnection
+The WebSocket client implements exponential backoff reconnection:
+- Delays: 1s, 2s, 4s, 8s, 16s, 30s (capped)
+- Max 10 attempts before showing "Reconnect" button
+- Call `forceReconnect()` to manually retry
+
+### Component Communication
+Components communicate via custom events that bubble through Shadow DOM:
+```typescript
+this.dispatchEvent(new CustomEvent('save', {
+  bubbles: true,
+  composed: true,  // Crosses shadow boundaries
+  detail: { ... }
+}));
+```
+
+## Common Tasks
+
+### Adding a New Component
+1. Create `client/src/components/my-component.ts`
+2. Use `@customElement('zing-my-component')` decorator
+3. Import in `zing-ui.ts`
+4. Add to render method with event handlers
+
+### Adding a New Agent
+1. Create `server/src/agents/my-agent.ts`
+2. Extend `BaseAgent` class
+3. Implement `createSession()` method
+4. Register in `server/src/index.ts` agent registry
+
+### Modifying the Toolbar
+Edit `client/src/components/toolbar.ts`:
+- Add new `@property()` for state
+- Add button in `render()` method
+- Create handler method that dispatches event
+- Wire up event in `zing-ui.ts`
+
+## Testing
+
+Test pages are available at:
+- `http://localhost:5200/` - Main demo page
+- `http://localhost:5200/products.html` - Product cards
+- `http://localhost:5200/about.html` - About page with stats/timeline
+- `http://localhost:5200/contact.html` - Contact form and FAQ
+
+## Build Output
+
+The Vite build produces:
+- `dist/zingit.es.js` - ES module version
+- `dist/zingit.iife.js` - IIFE for bookmarklet injection
+
+The IIFE can be used as a bookmarklet:
+```javascript
+javascript:(function(){var s=document.createElement('script');s.src='http://localhost:5200/dist/zingit.iife.js';document.body.appendChild(s);})()
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Wahlin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+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,301 @@
+# ZingIt
+
+A browser-based annotation tool that lets you highlight and comment on UI elements, then send those annotations to an AI agent for automated fixes.
+
+## Features
+
+- **Visual Annotations**: Click any element to add notes about changes you want
+- **Smart Selectors**: Automatically generates CSS selectors for targeted elements
+- **AI Integration**: Supports Claude Agent SDK, GitHub Copilot SDK, and OpenAI Codex SDK
+- **Streaming Responses**: Watch the AI work in real-time
+- **Persistent Storage**: Annotations survive page refreshes
+- **Bookmarklet Ready**: Single-file build for easy injection
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+# Server
+cd server
+npm install
+
+# Client
+cd ../client
+npm install
+```
+
+### 2. Start the Server
+
+The server requires two environment variables:
+- `PROJECT_DIR` - Path to the project the AI agent should work in
+- `AGENT` - Which AI agent to use (`claude`, `copilot`, or `codex`)
+
+```bash
+cd server
+
+# Using Claude Agent SDK
+PROJECT_DIR=/path/to/your/project AGENT=claude npm run dev
+
+# Using GitHub Copilot SDK
+PROJECT_DIR=/path/to/your/project AGENT=copilot npm run dev
+
+# Using OpenAI Codex SDK
+PROJECT_DIR=/path/to/your/project AGENT=codex npm run dev
+```
+
+The agent will read and edit files within the specified `PROJECT_DIR`.
+
+You can also override this per-session in the client settings (see Configuration).
+
+### 3. Start the Client Dev Server
+
+```bash
+cd client
+npm run dev
+```
+
+The browser will open automatically to `http://localhost:5200` with the demo page.
+
+## Usage
+
+1. **Click any element** on the page to open the annotation modal
+2. **Add notes** describing the issue or change you want
+3. **Repeat** for multiple elements
+4. Click **"Send to Agent"** to send all annotations to the AI
+5. Watch the **response panel** for the agent's work
+
+### Keyboard Shortcuts
+
+- `P` - Toggle annotation mode on/off
+- `Escape` - Close modals/panels
+- `Cmd/Ctrl + Enter` - Save annotation in modal
+
+## Building for Production
+
+### Bookmarklet
+
+Build a single-file version that can be injected via bookmarklet:
+
+```bash
+cd client
+npm run build
+```
+
+The `dist/zingit.iife.js` file contains everything needed. Create a bookmarklet:
+
+```javascript
+javascript:(function(){var s=document.createElement('script');s.src='http://localhost:5200/zingit.iife.js';document.body.appendChild(s);})()
+```
+
+### ES Module
+
+For integration into existing projects:
+
+```bash
+cd client
+npm run build
+```
+
+Use `dist/zingit.es.js` as an ES module.
+
+## Configuration
+
+Click the **gear icon** in the toolbar to open settings:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| WebSocket URL | `ws://localhost:8765` | Server connection URL |
+| Project Directory | *(empty)* | Override server's default project directory. Leave empty to use server default (shown as placeholder) |
+| Highlight Color | `#fbbf24` | Color of element highlight on hover |
+| Marker Color | `#3b82f6` | Color of numbered annotation markers |
+| Auto-connect | `true` | Connect to server on startup |
+
+Settings are saved to localStorage.
+
+**Project Directory Priority:**
+1. Client setting (if specified) - highest priority
+2. Server's `PROJECT_DIR` environment variable (required)
+
+## Architecture
+
+```
+zingit/
+├── client/                 # Browser-side Lit components
+│   ├── src/
+│   │   ├── components/    # Lit web components
+│   │   │   ├── zing-ui.ts    # Main orchestrator
+│   │   │   ├── toolbar.ts    # Status and actions
+│   │   │   ├── highlight.ts  # Hover overlay
+│   │   │   ├── markers.ts    # Numbered badges
+│   │   │   ├── modal.ts      # Annotation form
+│   │   │   ├── settings.ts   # Config panel
+│   │   │   └── response.ts   # AI response display
+│   │   ├── services/      # WebSocket, storage, selectors
+│   │   ├── utils/         # Geometry, markdown helpers
+│   │   └── types/         # TypeScript interfaces
+│   └── vite.config.ts
+│
+└── server/                 # WebSocket server + AI agents
+    └── src/
+        ├── agents/
+        │   ├── base.ts       # Abstract agent interface
+        │   ├── claude.ts     # Claude Agent SDK integration
+        │   ├── copilot.ts    # GitHub Copilot SDK integration
+        │   └── codex.ts      # OpenAI Codex SDK integration
+        ├── types.ts
+        └── index.ts          # WebSocket server
+```
+
+## Agents
+
+### GitHub Copilot SDK
+
+Uses the official `@github/copilot-sdk` package. Requires:
+- GitHub Copilot CLI installed and in your PATH
+- Active GitHub Copilot subscription
+
+The SDK communicates with the Copilot CLI in server mode, handling session management, streaming responses, and tool execution automatically.
+
+```bash
+# Install Copilot CLI first
+gh extension install github/gh-copilot
+
+# Then run the server
+PROJECT_DIR=/path/to/your/project AGENT=copilot npm run dev
+```
+
+### Claude Agent SDK
+
+Uses the official `@anthropic-ai/claude-agent-sdk` package. Requires:
+- Claude Code installed: `npm install -g @anthropic-ai/claude-code`
+- Valid Anthropic API key or Claude Max subscription
+
+The SDK provides streaming responses with tool execution status, allowing the agent to read files, search code, and make edits.
+
+```bash
+PROJECT_DIR=/path/to/your/project AGENT=claude npm run dev
+```
+
+### OpenAI Codex SDK
+
+Uses the official `@openai/codex-sdk` package. Requires:
+- Codex CLI installed and logged in (run `codex` once to authenticate)
+- Active ChatGPT Plus, Pro, Business, Edu, or Enterprise subscription
+
+The SDK uses your cached Codex CLI credentials (`~/.codex/auth.json`) - no API key needed. Just login once via the browser flow.
+
+```bash
+# First time: login to Codex (opens browser)
+npx codex
+
+# Then run the server
+PROJECT_DIR=/path/to/your/project AGENT=codex npm run dev
+```
+
+You can optionally set `CODEX_MODEL` to override the default model (gpt-5.2-codex).
+
+## API
+
+### WebSocket Messages
+
+**Client → Server:**
+
+```typescript
+// Send batch of annotations
+{ type: 'batch', data: { pageUrl, pageTitle, annotations, projectDir? } }
+
+// Send follow-up message
+{ type: 'message', content: '...' }
+
+// Reset session
+{ type: 'reset' }
+```
+
+Note: `projectDir` is optional. If omitted, the server uses its default (from `PROJECT_DIR` env var or cwd).
+
+**Server → Client:**
+
+```typescript
+{ type: 'connected', agent: 'claude', model: 'claude-sonnet-4-20250514', projectDir: '/path/to/project' }
+{ type: 'processing' }
+{ type: 'delta', content: '...' }     // Streaming text
+{ type: 'tool_start', tool: '...' }   // Tool execution started
+{ type: 'tool_end' }                  // Tool execution ended
+{ type: 'idle' }                      // Processing complete
+{ type: 'error', message: '...' }
+{ type: 'reset_complete' }
+```
+
+## Troubleshooting
+
+### "WebSocket not connected"
+
+1. Ensure the server is running (`npm run dev` in `/server`)
+2. Check the WebSocket URL in settings
+3. Check browser console for connection errors
+4. Click "Reconnect" if max attempts reached
+
+### "Claude Code CLI not found"
+
+Install Claude Code globally:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+### Annotations not persisting
+
+- Check if localStorage is available and not full
+- Annotations are URL-specific; changing pages clears them
+
+### Elements not highlighting
+
+- ZingIt ignores its own elements (anything starting with `zing-`)
+- Some elements may have pointer-events disabled
+
+## Development
+
+### Type Checking
+
+```bash
+# Client
+cd client && npm run typecheck
+
+# Server
+cd server && npm run typecheck
+```
+
+### Testing
+
+The server includes a test suite to validate agent WebSocket communication.
+
+```bash
+cd server
+
+# Run a single test (requires server to be running)
+npm run test                    # Simple scenario
+npm run test -- --scenario=multi    # Multiple annotations
+npm run test -- --scenario=followup # With follow-up message
+
+# Run all agents (starts/stops server automatically)
+npm run test:all               # Test all agents
+npm run test:copilot           # Test only Copilot
+npm run test:claude            # Test only Claude
+npm run test:codex             # Test only Codex
+
+# Dry run to see what would be tested
+./tests/run-all-tests.sh --dry-run
+```
+
+The test suite uses a sample project in `tests/test-project/` with a React file for agents to modify. Test scenarios send annotated UI changes and verify the agent responds correctly.
+
+### Project Structure
+
+The client uses Lit 3.x web components with Shadow DOM enabled for style isolation. This is critical for the bookmarklet use case where ZingIt must not conflict with the host page's styles.
+
+The server is a simple WebSocket relay that forwards annotation data to the configured AI agent and streams responses back.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { spawn } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m'
+};
+
+function printBanner() {
+  console.log('');
+  console.log(`${colors.cyan}╔═══════════════════════════════════════════════════════════════╗${colors.reset}`);
+  console.log(`${colors.cyan}║                                                               ║${colors.reset}`);
+  console.log(`${colors.cyan}║${colors.reset}  ${colors.bright}⚡ ZingIt${colors.reset} - AI-Powered UI Annotation Tool            ${colors.cyan}║${colors.reset}`);
+  console.log(`${colors.cyan}║                                                               ║${colors.reset}`);
+  console.log(`${colors.cyan}╚═══════════════════════════════════════════════════════════════╝${colors.reset}`);
+  console.log('');
+}
+
+function printInstructions(port = 3000) {
+  console.log(`${colors.green}✓${colors.reset} Server running at ${colors.bright}http://localhost:${port}${colors.reset}`);
+  console.log('');
+  console.log(`${colors.yellow}📝 How to use ZingIt:${colors.reset}`);
+  console.log('');
+  console.log(`   ${colors.bright}1.${colors.reset} Add to your webpage:`);
+  console.log(`      ${colors.cyan}<script src="https://cdn.jsdelivr.net/npm/@codewithdan/zingit@latest/dist/zingit-client.js"></script>${colors.reset}`);
+  console.log(`      ${colors.cyan}<script>ZingIt.connect('ws://localhost:${port}');</script>${colors.reset}`);
+  console.log('');
+  console.log(`   ${colors.bright}2.${colors.reset} Or visit the demo page:`);
+  console.log(`      ${colors.blue}http://localhost:${port}${colors.reset}`);
+  console.log('');
+  console.log(`   ${colors.bright}3.${colors.reset} Press ${colors.bright}Z${colors.reset} to toggle annotation mode`);
+  console.log('');
+  console.log(`${colors.yellow}💡 Tip:${colors.reset} Make sure you have an AI agent running (Claude Code, GitHub Copilot CLI, or OpenAI Codex)`);
+  console.log('');
+  console.log(`Press ${colors.bright}Ctrl+C${colors.reset} to stop the server`);
+  console.log('');
+}
+
+async function startServer() {
+  printBanner();
+  console.log(`${colors.cyan}🚀 Starting ZingIt server...${colors.reset}`);
+  console.log('');
+
+  // Path to the compiled server
+  const serverPath = join(__dirname, '..', 'server', 'dist', 'index.js');
+
+  // Start the server as a child process
+  const serverProcess = spawn('node', [serverPath], {
+    stdio: 'inherit',
+    env: { ...process.env, NODE_ENV: 'production' }
+  });
+
+  serverProcess.on('error', (err) => {
+    console.error(`${colors.red}✗ Failed to start server:${colors.reset}`, err);
+    process.exit(1);
+  });
+
+  // Wait a moment for server to start, then print instructions
+  setTimeout(() => {
+    printInstructions();
+  }, 1000);
+
+  // Handle graceful shutdown
+  process.on('SIGINT', () => {
+    console.log('');
+    console.log(`${colors.yellow}⚡ Shutting down ZingIt server...${colors.reset}`);
+    serverProcess.kill('SIGINT');
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    serverProcess.kill('SIGTERM');
+    process.exit(0);
+  });
+}
+
+startServer().catch((err) => {
+  console.error(`${colors.red}✗ Error:${colors.reset}`, err);
+  process.exit(1);
+});