rollbar 2.26.4 → 3.0.0-alpha.2

package/.claude/settings.local.json

@@ -0,0 +1,3 @@
+{
+  "enableAllProjectMcpServers": false
+}

package/.cursor/rules/guidelines.mdc

@@ -0,0 +1,154 @@
+---
+description: Rollbar JS SDK Guidelines
+globs:
+alwaysApply: true
+---
+
+## About Rollbar.js
+
+Rollbar.js is the official JavaScript SDK for the Rollbar error monitoring service. This library is not standalone - it works in tandem with the Rollbar platform to help developers detect, diagnose, and fix errors in real-time. The SDK sends error data to Rollbar's cloud service where errors are processed, grouped, and notifications are triggered.
+
+The library works across platforms, supporting both browser and server-side JavaScript including frameworks like React, Angular, Express, and Next.js. Key features include:
+
+- Cross-platform error tracking for client and server-side code
+- Telemetry to provide context around errors (breadcrumbs of events)
+- Automatic error grouping to reduce noise
+- Real-time notifications for critical issues
+- Detailed stack traces with source maps support
+- Distributed tracing and session management
+- Session replay capabilities for reproducing user actions
+
+## Project Structure
+
+```
+src/
+├── browser/      # Browser-specific implementation
+├── server/       # Node.js-specific implementation
+├── react-native/ # React Native implementation
+├── tracing/      # Distributed tracing support
+└── utility/      # Shared utility functions
+```
+
+## Build & Test Commands
+
+- Build: `npm run build` (runs Grunt)
+- Lint: `npm run lint` (ESLint)
+- Test all: `npm run test` (runs both server and browser tests)
+- Test browser only: `npm run test-browser`
+- Test server only: `npm run test-server`
+- Test specific browser test: `grunt test-browser:specificTestName`
+  - Example: `grunt test-browser:transforms`
+- Single test: `./node_modules/.bin/karma start --single-run --files={path/to/test}`
+
+## Modern Development Environment
+
+As of version 3.0.0, the SDK has been updated to use modern JavaScript features with appropriate transpilation:
+
+- **ES Modules**: The codebase supports ES modules (`import/export`) syntax
+- **Target Compatibility**:
+  - Source code uses ECMAScript 2021 features
+  - Builds target ES5 for broad browser compatibility
+  - Lower versions can use the ES5/CommonJS compatible bundles
+- **Build System**:
+  - Webpack 5 with Babel for transpilation
+  - ESLint for code quality
+  - Configurable output formats (UMD, AMD, vanilla)
+- **Minimum Node.js**: Version 18+ for absolute imports
+- **Toolchain Configuration**:
+  - `babel.config.json`: Controls transpilation options
+  - `eslint.config.mjs`: Modern ESLint flat config format
+  - `webpack.config.js`: Manages bundling and output formats
+
+## Code Style Guidelines
+
+- Use single quotes for strings
+- Use camelCase for variables (underscore prefix for private)
+- Indentation: 2 spaces
+- Include trailing commas in multiline objects/arrays
+- Max function complexity: 35
+- Unused parameters prefixed with underscore: `function(a, _unused) {}`
+- No whitespace in empty lines
+- Files should end with exactly one newline
+- Control statements (if, for, while, etc.) MUST use braces and newlines, even for single statements
+- Opening braces should be on the same line as the control statement
+- ESLint is used for enforcing code style
+- Prettier for code formatting
+
+## SDK Design Principles
+
+- **User Problems Are SDK Improvement Opportunities**: When users encounter integration issues, treat these as SDK design improvements rather than user implementation mistakes.
+  - Focus on enhancing the SDK to be more robust, intuitive and resilient
+  - Implement automatic environment detection and appropriate behavior selection
+  - Design APIs that work correctly across all supported contexts without requiring special user handling
+  - Errors should be informative and suggest correct usage patterns
+  - The burden of complexity should rest with the SDK, not its users
+
+## Error Handling
+
+- Prefer try/catch blocks around risky operations
+- Log errors through Rollbar's own logger system
+- Scrub sensitive fields in error payloads (see package.json defaults)
+- The codebase uses a comprehensive error tracking approach with appropriate levels:
+  - Debug level for development info
+  - Warning level for non-critical issues
+  - Error level for uncaught exceptions
+
+## TypeScript Support
+
+- Type definitions in index.d.ts
+- Add JSDoc types to enable intellisense when needed
+
+## Common Patterns
+
+When working with this codebase, be aware of these patterns:
+
+- Error transformation and normalization before sending
+- Telemetry collection for context
+- Queue-based sending with retry logic
+- Environment and context detection
+- Scrubbing of sensitive data
+
+## Testing Philosophy
+
+- **Analyze Test Failures Objectively**: When tests fail, evaluate both possibilities objectively:
+
+  - The test could be correctly identifying an actual code issue
+  - The test itself might contain errors or invalid expectations
+
+- **Diagnostic Process**:
+
+  1. Examine what the test is expecting vs. what the code actually does
+  2. Consider the intended behavior and design of the system
+  3. If the test is correct and identifying a legitimate bug, fix the code
+  4. If the test contains misconceptions or errors, fix the test
+
+- **Default to Code Quality**: When in doubt and both seem potentially valid, prioritize improving code quality over modifying tests to pass
+
+## Tracing & Session Replay
+
+The `src/tracing/` directory contains an OpenTelemetry-inspired tracing implementation that powers both distributed tracing and session recording features:
+
+### Components
+
+- **Context & ContextManager**: Manages propagation of tracing context through the application
+- **Span**: Represents a unit of work or operation with timing information and attributes
+- **Tracer**: Creates and manages spans for tracking operations
+- **SpanProcessor & SpanExporter**: Processes and exports spans to their destination
+- **Session**: Manages browser session data persistence and creation
+
+### Usage Patterns
+
+- **Tracing initialization**: Initialize via the main Tracing class with appropriate configuration
+- **Context propagation**: Use context to pass trace information between components
+- **Span creation**: Create spans to measure operations with `startSpan()`
+- **Attributes and events**: Add metadata to spans with `setAttribute()` and `addEvent()`
+- **Session management**: Automatically manages user sessions via browser sessionStorage
+
+### Integration with Session Replay
+
+The Session Replay feature utilizes this tracing infrastructure to:
+
+- Track and record user sessions with unique identifiers
+- Associate spans with specific user sessions for complete context
+- Capture timing information for accurate playback
+- Store interaction events as span attributes and events

package/.github/workflows/ci.yml

@@ -9,19 +9,17 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
 
     strategy:
       matrix:
         include:
-          - node: 14
-            npm: ^8
-          - node: 16
-            npm: ^8
           - node: 18
             npm: ^9
           - node: 20
             npm: ^10
+          - node: 22
+            npm: ^10
           - node: latest
             npm: latest
 
@@ -50,4 +48,4 @@ jobs:
           eslint_extensions: js
 
       - name: Run tests
-        run: npm run test_ci
+        run: npm run test-ci

package/CLAUDE.local.md

@@ -0,0 +1,297 @@
+# CLAUDE.local.md - Modernization Project
+
+## Problem Statement
+
+1. **Testing Infrastructure**: Karma is deprecated and unmaintained, and Vows.js (last commit 5 years ago) is abandoned with incompatible modern dependencies, creating multiple obsolete toolchain dependencies.
+
+2. **Limited TypeScript Support**: The SDK provides a limited amount of .d.ts files but lacks compilation pipeline and automated type checking in CI, leading to type definition errors discovered only through user reports.
+
+3. **Inconsistent Code Quality**: No automated formatting enforcement and limited linting integration in CI allows inconsistent code style and quality issues to persist across the codebase.
+
+4. **Legacy Tooling**: Grunt is effectively obsolete with minimal maintenance (last release 2 years ago, 703K weekly downloads vs 29M+ for modern alternatives), representing outdated task-runner architecture superseded by direct bundler usage.
+
+5. **Perception**: Enterprise engineers who evaluate our SDK examine our GitHub repository and development practices. Our outdated tooling stack creates an unfavorable impression that can influence their technology adoption decisions.
+
+### Why Consider Modernization Beyond TypeScript Requirements
+
+While not required for TypeScript, selective tooling improvements offer compelling technical benefits:
+
+1. **Configuration Complexity**: Current Grunt setup requires 273 lines just to orchestrate tools
+2. **Maintenance Burden**: Grunt plugins often lag behind their underlying tools
+3. **Developer Experience**: Modern tools provide better error messages, faster rebuilds, improved debugging
+4. **Ecosystem Alignment**: Most TypeScript tutorials/examples assume modern tooling (npm scripts, direct tool usage)
+5. **Build Performance**: Modern bundlers (Rollup, esbuild) are significantly faster than Webpack for libraries
+6. **Simpler Mental Model**: Direct tool usage (`"build": "webpack"`) vs indirection (`"build": "grunt"`)
+
+## Proposed Solution
+
+**Goal**: Incrementally modernize Rollbar.js development toolchain through targeted infrastructure improvements, enabling TypeScript support and enhanced developer productivity.
+
+**Strategic Approach**: This is a **mature SDK/Library** with extensive production usage. Our approach prioritizes:
+
+- **Zero disruption** to existing users and API surface
+- **Incremental improvements** that can be validated at each step
+- **Backwards compatibility** maintained throughout the process
+- **Risk mitigation** through careful, staged implementation
+
+**Project Type**: This is a **JavaScript SDK/Library**, not a web application. Our tooling choices should prioritize:
+
+- Multiple distribution formats (ES modules, CommonJS, UMD, browser bundles, <script> tag)
+- Tree-shaking compatibility for consuming applications
+- Minimal runtime dependencies
+- Package publishing and versioning workflows
+- Cross-platform compatibility (Node.js, browsers, React Native, browser extensions, Electron)
+
+**Change Philosophy**: Rather than wholesale replacement, we propose strategic improvements that:
+
+1. Enable TypeScript development and compilation capabilities
+2. Improve developer experience through targeted tooling updates
+3. Enhance build performance while maintaining all existing outputs
+4. Provide foundation for future maintainability improvements
+
+## Working Relationship & Learning Focus
+
+- You (matux) are an experienced systems programmer (C/C++, Rust) learning web development ecosystem
+- Claude acts as both implementation partner AND professor/teacher
+- **Didactic Approach**: Claude will explain the "why" behind every tool choice, architectural decision, and modernization step
+- **Educational Goals**: Understanding modern web development tooling, build systems, and JavaScript/TypeScript ecosystem
+
+## Current State Analysis
+
+### Legacy Tooling Stack
+
+- **Build System**: Grunt (circa 2012-2014 technology)
+- **Module System**: Mixed CommonJS/UMD with manual bundling
+- **Linting**: ESLint with flat config (partially modern)
+- **Testing**: Karma (deprecated) + Vows.js (abandoned)
+- **Bundling**: Webpack 5 (modern, but limited configuration)
+- **Target Compatibility**: ES5 for broad browser support
+- **TypeScript**: Only type definitions (index.d.ts), no compilation pipeline
+
+### Modernization Challenges
+
+1. **Grunt Dependency**: Heavy reliance on Grunt for build orchestration
+2. **Mixed Module Systems**: Inconsistent import/export patterns
+3. **Limited TypeScript**: No compilation pipeline, only definitions
+4. **Legacy Browser Support**: ES5 targeting limits modern feature adoption
+5. **Build Complexity**: Multiple output formats (UMD, AMD, vanilla) with manual configuration
+
+## Educational Context: Why These Tools Matter for Libraries
+
+### Build Systems Evolution (Library Perspective)
+
+- **Grunt (2012)**: Configuration-heavy task runner, good for complex multi-step builds
+- **Rollup (2015)**: **Ideal for libraries** - ES module-first, excellent tree-shaking, minimal output
+- **Webpack (2012-present)**: Application-focused bundler, heavier runtime, less optimal for libraries
+- **esbuild (2020)**: Ultra-fast bundler/transpiler, excellent for library compilation
+- **tsup (2021)**: Modern library build tool, TypeScript-first, zero-config approach
+
+### Library-Specific Tooling Considerations
+
+1. **Bundle Size**: Libraries should minimize size impact on consuming applications
+2. **Module Formats**: Must support multiple formats (ESM, CJS, UMD) for compatibility
+3. **Tree-Shaking**: Enable dead code elimination in consuming applications
+4. **Peer Dependencies**: Minimize runtime dependencies to avoid version conflicts
+5. **API Surface**: TypeScript definitions crucial for developer experience
+
+### TypeScript Integration for Libraries
+
+1. **Declaration Generation**: Automatic .d.ts file generation from TypeScript source
+2. **Multiple Targets**: Compile to different module systems simultaneously
+3. **API Compatibility**: Ensure TypeScript changes don't break JavaScript consumers
+4. **Type-Only Imports**: Optimize bundle size by removing type-only code
+
+## Implementation Strategy: Incremental Enhancement
+
+**Key Finding**: TypeScript support does NOT require wholesale tooling replacement. We can enable TypeScript capabilities through targeted enhancements to existing infrastructure.
+
+**Proposal Rationale**: This approach minimizes risk while delivering immediate value to the development team.
+
+### Current Build Analysis
+
+- **Grunt Role**: Orchestrates Webpack, Karma tests, and snippet replacement (273 lines of config)
+- **Webpack Role**: Bundling and minification; Babel transpilation added in v3.x for modern JS/TS support
+- **Karma Issues**: Outdated architecture, complex configuration, performance bottlenecks
+- **Opportunity**: Modern Web Test Runner + TypeScript integration eliminates testing complexity
+
+## Implementation Plan
+
+**Primary Goal**: Enable TypeScript support through incremental, validated improvements.
+
+### Phase 1: Complete ES Modules Migration
+
+**Rationale**: The mixture of CommonJS and ESM files makes migrating away from Karma to modern solutions like Web Test Runner significantly more difficult. Standardizing on ES modules across the entire codebase will simplify subsequent modernization efforts and provide a consistent module system.
+
+**Critical Finding**: Vows.js is fundamentally incompatible with ES modules and blocks server test migration. This must be addressed before completing the ES module migration.
+
+1. **Partial Test Migration to ES Modules** ✅
+
+   - Migrated 19 of 27 test files from CommonJS to ES modules
+   - 8 server test files remain blocked due to Vows.js dependency
+   - Migration pattern: `require()` → `import`, add `.js` extensions
+   - Completed: utility, API, browser, platform, and example tests
+
+2. **Migrate Vows.js to Mocha** ✅
+
+   - Replace abandoned Vows.js (last commit 5 years ago) with Mocha
+   - Unify test frameworks across browser and server tests
+   - Convert Vows patterns: topics → `beforeEach`, batches → `describe`
+   - Maintain test coverage and assertion equivalence
+
+3. **Complete Server Test ES Module Migration** ✅
+
+   - Convert 8 remaining server test files to ES modules
+   - Update imports and add `.js` extensions
+   - Ensure Node.js test runner supports ES modules
+   - Validate all server tests pass with new module system
+
+4. **Migrate Source Code to ES Modules** ✅
+   - Start with leaf modules (no internal dependencies)
+   - Progress to core modules while maintaining API compatibility
+   - Update build configuration for native ES module handling
+   - Preserve all distribution formats (CommonJS, UMD, ES modules)
+
+### Phase 2: Modern Testing & TypeScript Foundation
+
+1. **Migrate from Karma to Web Test Runner**
+
+   - Replace Karma with @web/test-runner for modern, performant browser testing
+   - Maintain existing Mocha + Chai + Sinon test framework
+   - Configure native TypeScript support without complex preprocessors
+   - Update CI/CD pipeline to use new test runner
+   - See detailed migration plan in CLAUDE.testrunner.md
+
+2. **Add TypeScript to Build Pipeline**
+
+   - Install TypeScript and `@babel/preset-typescript`
+   - Configure Babel preset for TypeScript compilation
+   - Add `tsconfig.json` for type checking and IDE support
+   - Update Webpack config to handle `.ts` files
+
+3. **Validation & Testing**
+   - Convert small utility functions to TypeScript
+   - Verify existing build outputs remain unchanged
+   - Test type checking and compilation pipeline
+   - Ensure IDE integration works properly
+   - Validate all tests pass with new test runner
+
+### Phase 3: Code Quality Standardization
+
+**Rationale**: ESLint and Prettier are configured after TypeScript support to enable unified configuration for both JavaScript and TypeScript files, avoiding the need to reconfigure linting rules when TypeScript plugins are added.
+
+1. **Modernize ESLint Configuration**
+
+   - Review and update ESLint rules for modern JavaScript/TypeScript compatibility
+   - Configure ESLint to work seamlessly with TypeScript files
+   - Standardize code style rules across browser, server, and test code
+   - Add ESLint plugins for better error detection and modern practices
+
+2. **Integrate Prettier for Consistent Formatting**
+
+   - Add Prettier configuration for automated code formatting
+   - Configure Prettier to work alongside ESLint without conflicts
+   - Define formatting rules that align with existing code style preferences
+   - Set up editor integration for automatic formatting on save
+
+3. **CI/CD Integration**
+
+   - Add linting and formatting checks to continuous integration pipeline
+   - Configure CI to fail builds on linting errors or formatting violations
+   - Implement automated formatting validation for pull requests
+   - Ensure consistent code quality enforcement across all contributions
+
+4. **Developer Workflow Enhancement**
+   - Add npm scripts for linting (`npm run lint`) and formatting (`npm run format`)
+   - Set up pre-commit hooks using Husky for automatic code quality checks
+   - Update development documentation with code style guidelines
+   - Ensure compatibility with popular editors and IDEs
+
+### Phase 4: Build System Migration
+
+**Rationale**: Grunt is unmaintained (last release 2 years ago) and adds unnecessary complexity. Direct tool usage via npm scripts provides better performance, clearer workflows, and easier maintenance.
+
+1. **Audit Current Build Process**
+
+   - Map all Grunt tasks and their purposes
+   - Document all output formats (UMD, ES modules, minified versions)
+   - Analyze bundle sizes and compilation times
+   - Identify pain points in current developer workflow
+
+2. **Research Modern Alternatives**
+
+   - Evaluate continuing with Webpack vs migrating to library-focused alternatives (Rollup, esbuild, tsup)
+   - Compare build performance and output quality
+   - Assess migration complexity for each option
+   - Plan strategy to maintain all current outputs
+
+3. **Replace Grunt with Direct Tool Usage**
+   - Migrate to npm scripts calling tools directly
+   - Implement modern bundling with library-optimized tools
+   - Maintain all existing output formats
+   - Optimize for tree-shaking and bundle efficiency
+
+### Phase 5: TypeScript Migration
+
+1. **Systematic TypeScript Conversion**
+   - Start with utility functions and shared code
+   - Convert platform-specific implementations
+   - Maintain JavaScript API compatibility
+   - Enable stricter TypeScript settings incrementally
+
+### Phase 6: Developer Experience & Library Enhancements
+
+1. **Enhanced Development Experience**
+
+   - Fast TypeScript compilation with watch mode
+   - Improved source maps and debugging
+   - Better error reporting and build feedback
+   - Hot module replacement for development
+
+2. **Library-Specific Enhancements**
+   - Automatic declaration file generation
+   - Type-only import optimization
+   - Enhanced IDE support and developer experience
+   - Cross-platform TypeScript testing
+
+## Success Criteria
+
+1. **TypeScript Support**: Full compilation pipeline with declaration generation
+2. **Multiple Formats**: ESM, CJS, UMD outputs all maintained
+3. **Tree-Shaking**: Consuming applications can eliminate unused code
+4. **Developer Experience**: Fast builds, excellent IDE support
+5. **Backward Compatibility**: No breaking changes; existing users unaffected by development toolchain improvements
+6. **Bundle Efficiency**: Smaller or equivalent bundle sizes
+7. **Security**: All security alerts resolved (https://github.com/rollbar/rollbar.js/security/dependabot)
+
+---
+
+_This document will evolve as we learn and make decisions together. Each major decision will include educational context about why we chose specific approaches for library development._
+
+--
+
+## Next Steps
+
+**Current Status**: Phase 2.1 (Migrate from Karma to Web Test Runner) 🚧 Ready to Start
+
+- Phase 1.1: Partial Test Migration to ES Modules ✅
+- Phase 1.2: Migrate Vows.js to Mocha ✅
+- Phase 1.3: Complete Server Test ES Module Migration ✅
+- Phase 1.4: Migrate Source Code to ES Modules ✅ Complete
+
+**Phase 1 Completion Notes**:
+- Successfully migrated all source and test files from CommonJS to ES modules
+- Handled Node.js version compatibility for JSON imports using `createRequire`
+- All tests passing with ES module syntax
+- Package.json updated with `"type": "module"`
+- Configuration files renamed to `.cjs` extension for compatibility
+
+**Immediate Next Step**:
+
+- **Execute Karma to Web Test Runner Migration (Phase 2.1)** - Create a thorough and well-thought-out migration plan in CLAUDE.testrunner.md
+
+**Upcoming Steps**:
+
+1. **Add TypeScript to Build Pipeline (Phase 2.2)** - Enable TypeScript compilation without changing build system
+2. **Implement Code Quality Standards (Phase 3)** - Add Prettier and modernize ESLint configuration
+3. **Build System Migration (Phase 4)** - Replace Grunt with direct tool usage
+4. **TypeScript Migration (Phase 5)** - Systematic conversion to TypeScript

package/CLAUDE.md

@@ -0,0 +1,201 @@
+## About Rollbar.js
+
+Rollbar.js is the official JavaScript SDK for the Rollbar error monitoring service. This library is not standalone - it works in tandem with the Rollbar platform to help developers detect, diagnose, and fix errors in real-time. The SDK sends error data to Rollbar's cloud service where errors are processed, grouped, and notifications are triggered.
+
+The library works across platforms, supporting both browser and server-side JavaScript including frameworks like React, Angular, Express, and Next.js. Key features include:
+
+- Cross-platform error tracking for client and server-side code
+- Telemetry to provide context around errors (breadcrumbs of events)
+- Automatic error grouping to reduce noise
+- Real-time notifications for critical issues
+- Detailed stack traces with source maps support
+- Distributed tracing and session management
+- Session replay capabilities for reproducing user actions
+
+## Project Structure
+
+```
+src/
+├── browser/      # Browser-specific implementation
+├── server/       # Node.js-specific implementation
+├── react-native/ # React Native implementation
+├── tracing/      # Distributed tracing support
+└── utility/      # Shared utility functions
+```
+
+## Build & Test Commands
+
+- Build: `npm run build` (runs Grunt)
+- Lint: `npm run lint` (ESLint)
+- Test all: `npm run test` (runs both server and browser tests)
+- Test browser only: `npm run test-browser`
+- Test server only: `npm run test-server`
+- Test specific browser test: `grunt test-browser:specificTestName`
+  - Example: `grunt test-browser:transforms`
+- Single test: `./node_modules/.bin/karma start --single-run --files={path/to/test}`
+
+## Modern Development Environment
+
+As of version 3.0.0, the SDK has been updated to use modern JavaScript features with appropriate transpilation:
+
+- **ES Modules**: The codebase supports ES modules (`import/export`) syntax
+- **Target Compatibility**:
+  - Source code uses ECMAScript 2021 features
+  - Builds target ES5 for broad browser compatibility
+  - Lower versions can use the ES5/CommonJS compatible bundles
+- **Build System**:
+  - Webpack 5 with Babel for transpilation
+  - ESLint for code quality
+  - Configurable output formats (UMD, AMD, vanilla)
+- **Minimum Node.js**: Version 18+ for absolute imports
+- **Toolchain Configuration**:
+  - `babel.config.json`: Controls transpilation options
+  - `eslint.config.mjs`: Modern ESLint flat config format
+  - `webpack.config.js`: Manages bundling and output formats
+
+## Code Style Guidelines
+
+- Use single quotes for strings
+- Use camelCase for variables (underscore prefix for private)
+- Indentation: 2 spaces
+- Include trailing commas in multiline objects/arrays
+- Max function complexity: 35
+- Unused parameters prefixed with underscore: `function(a, _unused) {}`
+- No whitespace in empty lines
+- Files should end with exactly one newline
+- Control statements (if, for, while, etc.) MUST use braces and newlines, even for single statements
+- Opening braces should be on the same line as the control statement
+- ESLint is used for enforcing code style
+- Prettier for code formatting
+
+### Documentation vs. Comments
+
+- **Function Documentation (JSDoc/TSDoc)**: Always include comprehensive documentation for functions, classes, and methods using JSDoc/TSDoc format (`/** ... */`). These serve as API documentation, appear in IDE tooltips, and help developers understand purpose, parameters, and return values.
+
+- **Inline Code Comments**: Avoid redundant comments that merely restate what the code is doing. Only add comments to explain:
+  - Why the code works a certain way (decisions and reasoning)
+  - Non-obvious behavior or edge cases
+  - Complex algorithms or business logic
+  - Workarounds for bugs or limitations
+  
+- **Self-documenting Code**: Write clear, readable code that explains itself through descriptive variable/function names and straightforward logic. Well-written code rarely needs explanatory comments.
+
+- **Examples**:
+  ```javascript
+  // BAD - Redundant comment
+  // Add one to x
+  x += 1;
+  
+  // GOOD - Explains the non-obvious "why"
+  // Increment before sending to API to account for zero-indexing
+  x += 1;
+  ```
+
+## SDK Design Principles
+
+- **User Problems Are SDK Improvement Opportunities**: When users encounter integration issues, treat these as SDK design improvements rather than user implementation mistakes.
+  - Focus on enhancing the SDK to be more robust, intuitive and resilient
+  - Implement automatic environment detection and appropriate behavior selection
+  - Design APIs that work correctly across all supported contexts without requiring special user handling
+  - Errors should be informative and suggest correct usage patterns
+  - The burden of complexity should rest with the SDK, not its users
+
+## Error Handling
+
+- Prefer try/catch blocks around risky operations
+- Log errors through Rollbar's own logger system
+- Scrub sensitive fields in error payloads (see package.json defaults)
+- The codebase uses a comprehensive error tracking approach with appropriate levels:
+  - Debug level for development info
+  - Warning level for non-critical issues
+  - Error level for uncaught exceptions
+
+## TypeScript Support
+
+- Type definitions in index.d.ts
+- Add JSDoc types to enable intellisense when needed
+
+## Common Patterns
+
+When working with this codebase, be aware of these patterns:
+
+- Error transformation and normalization before sending
+- Telemetry collection for context
+- Queue-based sending with retry logic
+- Environment and context detection
+- Scrubbing of sensitive data
+
+## Testing Philosophy
+
+- **Analyze Test Failures Objectively**: When tests fail, evaluate both possibilities objectively:
+
+  - The test could be correctly identifying an actual code issue
+  - The test itself might contain errors or invalid expectations
+
+- **Diagnostic Process**:
+
+  1. Examine what the test is expecting vs. what the code actually does
+  2. Consider the intended behavior and design of the system
+  3. If the test is correct and identifying a legitimate bug, fix the code
+  4. If the test contains misconceptions or errors, fix the test
+
+- **Default to Code Quality**: When in doubt and both seem potentially valid, prioritize improving code quality over modifying tests to pass
+
+## Tracing & Session Replay
+
+The `src/tracing/` directory contains an OpenTelemetry-inspired tracing implementation that powers both distributed tracing and session recording features:
+
+### Components
+
+- **Context & ContextManager**: Manages propagation of tracing context through the application
+- **Span**: Represents a unit of work or operation with timing information and attributes
+- **Tracer**: Creates and manages spans for tracking operations
+- **SpanProcessor & SpanExporter**: Processes and exports spans to their destination
+- **Session**: Manages browser session data persistence and creation
+
+### Usage Patterns
+
+- **Tracing initialization**: Initialize via the main Tracing class with appropriate configuration
+- **Context propagation**: Use context to pass trace information between components
+- **Span creation**: Create spans to measure operations with `startSpan()`
+- **Attributes and events**: Add metadata to spans with `setAttribute()` and `addEvent()`
+- **Session management**: Automatically manages user sessions via browser sessionStorage
+
+### Session Replay Implementation
+
+The `src/browser/replay` directory contains the implementation of the Session Replay feature:
+
+- **Recorder**: Core class that integrates with rrweb to record DOM events
+- **ReplayMap**: Manages the mapping between error occurrences and session recordings
+- **Configuration**: Configurable options in `defaults.js` for replay behavior
+
+The Session Replay feature utilizes our tracing infrastructure to:
+
+- Record user interactions using rrweb in a memory-efficient way
+- Store recordings with checkpoints for better performance
+- Generate spans that contain replay events with proper timing
+- Associate recordings with user sessions for complete context
+- Transport recordings to Rollbar servers via the API
+
+### Session Replay Flow
+
+1. **Recording**: The Recorder class continuously records DOM events using rrweb
+2. **Error Occurrence**: When an error occurs, Queue.addItem() calls ReplayMap.add()
+3. **Correlation**: ReplayMap generates a replayId and attaches it to the error
+4. **Coordination**: After successful error submission, Queue triggers ReplayMap.send()
+5. **Transport**: ReplayMap retrieves stored replay data and sends via api.postSpans()
+
+### Testing Infrastructure
+
+- **Unit Tests**: Component-focused tests in `test/replay/unit/`
+- **Integration Tests**: Test component interactions in `test/replay/integration/`
+- **End-to-End Tests**: Full flow verification in `test/replay/integration/e2e.test.js`
+- **Mock Implementation**: `test/replay/util/mockRecordFn.js` provides a deterministic mock of rrweb
+- **Fixtures**: Realistic rrweb events in `test/fixtures/replay/` for testing
+- **Test Tasks**: Custom Grunt tasks for testing replay code specifically
+
+## File Creation Guidelines
+
+- **Newlines**: All new files MUST end with exactly one newline character
+- **Encoding**: Use UTF-8 encoding for all text files
+- **Line Endings**: Use LF (Unix-style) line endings, not CRLF