# StackScope SDK - Claude Code Instructions

## 📦 Package Overview
StackScope is a zero-config browser SDK for automatic log capture. This package contains the core SDK and React components.

## 🛠️ Development Commands
- `npm run build` - Build all SDK bundles (main + React)
- `npm run build:verify` - Build + comprehensive verification
- `npm run build:clean` - Clean dist and rebuild
- `npm test` - Run all tests (38 tests should pass)
- `npm run test:watch` - Watch mode for tests
- `npm run typecheck` - TypeScript type checking
- `npm run size` - Check bundle sizes and report
- `npm run dev` - Watch mode for development

## 📁 Project Structure
- `src/` - TypeScript source code
  - `src/index.ts` - Main SDK entry point
  - `src/react/` - React components and hooks
  - `src/domain/` - Core interfaces and types
  - `src/infrastructure/` - Concrete implementations
- `dist/` - Compiled JavaScript (generated)
- `templates/` - Environment variable templates
- `examples/` - Working integration examples
- `docs/` - Comprehensive documentation

## 🎯 Code Conventions
- **Architecture**: Clean Architecture - all logic depends on interfaces, never concrete classes
- **TypeScript**: Prefer interfaces over type aliases unless modeling data
- **Dependencies**: No runtime dependencies (zero bloat for consumers)
- **React**: Optional peerDependency, components in separate bundle
- **Testing**: All new features need tests using Vitest
- **Build**: Rollup with separate bundles for main SDK and React components

## 🧪 Testing Guidelines
- Run `npm test` - should always pass all 38 tests
- New components need corresponding test files
- Use `npm run build:verify` to ensure build integrity
- Integration tests should work without external dependencies

## ⚛️ React Development
- React components are in `src/react/`
- Built separately as `dist/react/index.esm.js` and `dist/react/index.js`
- Import path: `import { Component } from 'stackscope/react'`
- All React components are optional - but both SDK and worker are required for functionality

## 🔧 Common Tasks
- **Add new capture type**: Implement interface in `src/domain/interfaces/`
- **Add React component**: Create in `src/react/` and export from `src/react/index.ts`
- **Fix build issue**: Run `npm run build:verify` to see what's broken
- **Debug test failure**: Use `npm run test:watch` for interactive debugging
- **Check bundle size**: Use `npm run size` to see current sizes

## 🚨 Important Notes
- Never add runtime dependencies - this is a zero-dependency SDK
- Always run `npm run build:verify` before publishing
- React components should import from the built main SDK, not relative paths
- All TypeScript must compile without errors
- Bundle sizes: Main SDK ~21KB minified, React ~56KB

## 🏗️ Build Verification
The build creates these files:
- `dist/stackscope-sdk.esm.js` - ES module (49KB)
- `dist/stackscope-sdk.js` - UMD bundle (55KB) 
- `dist/stackscope-sdk.min.js` - Minified (21KB)
- `dist/react/index.esm.js` - React ES module (56KB)
- `dist/react/index.js` - React CommonJS (57KB)
- All TypeScript declarations (.d.ts files)

## 📚 Documentation Files
- `README.md` - Main package documentation
- `docs/integration-guide.md` - Detailed integration instructions
- `docs/troubleshooting.md` - Common issues and solutions
- `examples/` - Working code examples for different frameworks
- `templates/` - Environment configuration templates

## 🔄 Publishing Process
1. `npm run build:verify` (builds + verifies all outputs)
2. `npm test` (runs all tests)
3. `npm run typecheck` (validates TypeScript)
4. `npm publish` (publishes to npm)

## 💡 Tips for AI Assistants
- Check `examples/` folder for working integration patterns
- Use `docs/troubleshooting.md` for common issues
- Framework-specific env templates are in `templates/`
- All necessary documentation is included offline in this package
- Run verification commands to ensure changes work correctly