feat: allow isEnabled() to return undefined to defer to sampleRate (#26)

* feat: allow isEnabled() to return undefined to defer to sampleRate

When isEnabled() returns true or false, it force-enables or
force-disables as before. Returning undefined now falls through
to the sampleRate sampling logic, enabling patterns like
force-enabling for internal users while sampling everyone else.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: enable global mock restoration in Vitest config

Add `restoreMocks: true` to vitest.config.ts so vi.restoreAllMocks()
runs after every test, preventing mocked state (e.g. Math.random spies)
from leaking between tests. Remove redundant manual mockRestore() call.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: frankieyan

README.md

@@ -26,7 +26,10 @@ const cleanup = initInteractionTraceMonitor({
     },
     enrollment: {
         sampleRate: 10, // 10% of sessions
-        isEnabled: () => user.isInternal, // Optional override
+        isEnabled: () => {
+            if (user.isInternal) return true    // force enable for internal users
+            return undefined                     // everyone else: use sampleRate
+        },
     },
     abortSignal: controller.signal, // Optional: auto-cleanup when aborted
 })
@@ -103,7 +106,7 @@ function SettingsModal() {
 |--------|------|-------------|
 | `sampleRate` | `number` | Percentage of sessions to enroll (0-100) |
 | `persistKey` | `string` | sessionStorage key for enrollment state. Default: `'interaction-trace-enrolled'` |
-| `isEnabled` | `() => boolean` | Override function (takes precedence over sampleRate) |
+| `isEnabled` | `() => boolean \| undefined` | Override function. `true`/`false` override sampling, `undefined` defers to `sampleRate` |
 
 ### Reporter Interface
 

src/core/trace-controller.test.ts

@@ -94,8 +94,6 @@ describe('trace-controller', () => {
             )
             cleanup2()
             expect(isMonitorActive()).toBe(true)
-
-            consoleWarnSpy.mockRestore()
         })
     })
 
@@ -142,6 +140,34 @@ describe('trace-controller', () => {
             expect(isMonitorActive()).toBe(true)
         })
 
+        it('force disables when isEnabled returns false', () => {
+            const reporter = vi.fn()
+            initInteractionTraceMonitor({
+                reporter,
+                enrollment: {
+                    sampleRate: 100,
+                    isEnabled: () => false,
+                },
+            })
+
+            expect(isMonitorActive()).toBe(false)
+        })
+
+        it('falls back to sampleRate when isEnabled returns undefined', () => {
+            vi.spyOn(Math, 'random').mockReturnValue(0.05)
+
+            const reporter = vi.fn()
+            initInteractionTraceMonitor({
+                reporter,
+                enrollment: {
+                    sampleRate: 10,
+                    isEnabled: () => undefined,
+                },
+            })
+
+            expect(isMonitorActive()).toBe(true)
+        })
+
         it('reads existing enrollment from sessionStorage', () => {
             sessionStorage.setItem('interaction-trace-enrolled', 'false')
 

src/core/trace-controller.ts

@@ -186,7 +186,10 @@ signInteractionTrace.withTypes = function withTypes<
 
 function checkEnrollment(config: InteractionTraceConfig['enrollment']): boolean {
     if (config?.isEnabled) {
-        return config.isEnabled()
+        const result = config.isEnabled()
+        if (result !== undefined) {
+            return result
+        }
     }
 
     const sampleRate = config?.sampleRate ?? DEFAULT_SAMPLE_RATE

src/types.ts

@@ -61,8 +61,13 @@ export type EnrollmentConfig = {
     sampleRate?: number
     /** sessionStorage key for enrollment state. Default: 'interaction-trace-enrolled' */
     persistKey?: string
-    /** Override function - takes precedence over sampleRate if provided */
-    isEnabled?: () => boolean
+    /**
+     * Override function for enrollment.
+     * - `true` — force enable (skip sampling)
+     * - `false` — force disable (skip sampling)
+     * - `undefined` — defer to `sampleRate`
+     */
+    isEnabled?: () => boolean | undefined
 }
 
 /**

vitest.config.ts

@@ -6,5 +6,6 @@ export default defineConfig({
         include: ['src/**/*.test.{ts,tsx}'],
         watchExclude: ['node_modules', 'dist'],
         passWithNoTests: true,
+        restoreMocks: true,
     },
 })