feat: add core interaction trace monitoring implementation

[frankieyan]

This PR ports over the core Interaction Trace implementation from Todoist, bringing over the InteractionTrace class, and the trace-controller module. This does not yet include the React layer (just a think hook wrapper around signInteractionTrace), which will come in a later PR.

Note

Please don't be alarmed by the large diff 😅 the implementation mostly resembles the original implementation we have running on production for Todoist. I'll highlight the differences further below.

Example

import { initInteractionTraceMonitor, signInteractionTrace } from '@doist/interaction-trace'

// Initialize — sets up pointerup listener, returns cleanup function
const cleanup = initInteractionTraceMonitor<MyTraces>({
    reporter: (report) => sendToAnalytics(report),
    enrollment: {
        sampleRate: 10,                    // 10% of sessions
        persistKey: 'my-app-trace-enroll', // sessionStorage key, defaults to 'interaction-trace-enrolled'
        isEnabled: () => user.isInternal,  // Overrides sample rate
    },
    abortSignal: abortController.signal,        // Optional lifecycle control
})

// Sign the current pending trace during an interaction (no-op if none exists)
signInteractionTrace('open modal', { modalId: 'settings' })

// Cleanup all listeners
cleanup()

Trace lifecycle

[pointerup] → PENDING → [sign()] → ACTIVE → [LoAF settles] → COMPLETED (reported)
                ↓                     ↓ → [INP settles]
           [new pointerup]       [new pointerup]
                ↓                     ↓
            CANCELLED             CANCELLED
          (not reported)        (not reported)

Differences compared to Todoist's internal implementation

Aspect	todoist-web	@doist/interaction-trace
AbortSignal support	Init check only	Init check + runtime cleanup listener
cancel() behavior	Calls process(), creates measurements	Clears marks only, no measurements
Array cleanup	Cancelled traces stay until timer	Immediately cleared on cancel
Trace ID	uuid npm package	Native crypto.randomUUID()
Reporter	Datadog	Pluggable callback function

Cancelled traces in particular has a more significant change:

todoist-web:

Controller:

document.addEventListener('pointerup', () => {
    if (cleanupTimeout) clearTimeout(cleanupTimeout)

    // Immediately cancel all traces and create a new trace
    traces.map((trace) => trace.cancel())
    traces.push(new InteractionTrace())

    cleanupTimeout = setTimeout(
        // Clear all processed traces after 1s
        () => (traces = traces.filter((trace) => !trace.processed)),
        1000,
    )
})

Trace instance:

cancel() {
    this.canceled = true
    performance.mark(this.longFrames.markEndName)  // Creates end mark
    this.process()  // Still processes, creates measurements
    // report() checks `canceled` flag to skip reporting
}

@doist/interaction-trace:

Controller:

function handlePointerUp(): void {
    if (!reporter) return

    // Immediately cancel and let traces be garbage collected
    for (const trace of traces) {
        trace.cancel()
    }
    traces = []

    const trace = new InteractionTrace<TraceDetails>((report) => {
        reporter?.(report)
    })
    traces.push(trace)

    if (cleanupTimeoutId !== undefined) {
        clearTimeout(cleanupTimeoutId)
    }
    cleanupTimeoutId = setTimeout(() => {
        // Clear all processed and cancelled traces after 1s
        traces = traces.filter((t) => !t.isProcessed && !t.isCancelled)
        cleanupTimeoutId = undefined
    }, CLEANUP_TIMER_MS)
}

Trace instance:

cancel() {
    this._cancelled = true
    this.clearMarks()  // Clears existing marks
    this.cleanup()     // NO process() call, no measurements
}

Test plan

Nothing to test for for now. The next PR will be accompanied by a Todoist PR to test the integration.

[doistbot-app]

Thank you for porting over the core implementation for interaction trace monitoring. The logic is well-structured and is accompanied by a thorough suite of tests, aligning well with the stated goals. There may be correctness issues in server-side rendering or Node environments that could cause failures.

[Bloomca]

Looks good, just a few small questions

[Bloomca]

I am curious why this change? I checked and I have bash on Windows, but to be honest I do not know if it is generally available, so why not just keep it as an npm command?

[frankieyan]

It's to prevent lint-staged from passing file arguments to tsc, as that causes it to ignore tsconfig.json, but the lint-staged docs have a better way to do this: https://github.com/lint-staged/lint-staged#example-run-tsc-on-changes-to-typescript-files-but-do-not-pass-any-filename-arguments

[frankieyan]

Updated in 731080c

[Bloomca]

I am a bit confused by this change, shouldn't it stay types.mts?

[frankieyan]

To use the mts extension in the import path, we'd need the allowImportingTsExtensions option enabled in tsconfig.json, however, that will cause rollup to fail with:

(!) [plugin typescript] @rollup/plugin-typescript TS5096: Option 'allowImportingTsExtensions' can only be used when either 'noEmit' or 'emitDeclarationOnly' is set.

So, because we're transpiling from ts -> js, we can't have this enabled. But, we should be able to go back to plain .ts extensions. I'll explore that when working on CI/CD and the release flow.

[frankieyan]

@doistbot /review

[doistbot-app]

This PR ports over the core logic for interaction trace monitoring, including the InteractionTrace class and the trace-controller, establishing a great foundation for standardizing our performance tooling. The review flagged a couple of potential issues with how the performance observers are handled, one related to ensuring runtime safety in unsupported browsers and another concerning the management of performance marks.

[doistbot-app]

[P1] Creating the LoAF/INP PerformanceObservers without checking support will throw in browsers that don’t support long-animation-frame or event entry types (e.g., Safari), which crashes on any interaction. Since feature detection exists in this PR, guard observeLongAnimationFrames()/observeNextPaint() with isLoafSupported()/isInpSupported() (or wrap observe in a try/catch) so unsupported browsers safely skip observers.

[frankieyan]

@doistbot initInteractionTraceMonitor won't initialize if there's no support, so we don't need to feature-check each individual use case.

[doistbot-app]

Thanks for the clarification, Frankie. I understand the intention is for initInteractionTraceMonitor to act as the feature-detection guard before this class is ever used.

However, since InteractionTrace is an exported class, it could be instantiated directly elsewhere in the future, bypassing that check. This would re-introduce the crash in unsupported browsers because the constructor unconditionally creates the observers:

constructor(onComplete: TraceReporter<TDetails>) {
    // ...
    this.observeLongAnimationFrames()
    this.observeNextPaint()
}

To make the class more robust and prevent potential future issues, it would be best for it to be self-contained. Could we add the support checks within the observeLongAnimationFrames() and observeNextPaint() methods? This ensures InteractionTrace is always safe to instantiate, regardless of how it's imported or used.

[frankieyan]

It's not meant to be a part of the public API and is not documented as a use case, so IMHO it's fair we only feature-check at the publicly documented entry point.

[doistbot-app]

[P2] The performance.mark(this.markEndName) call on each LoAF callback overwrites the previous end mark without clearing it first. While performance.mark with the same name creates a new mark entry rather than updating it, calling clearMarks(this.markEndName) before setting the new one would prevent accumulating multiple end marks in the performance buffer. In practice this is unlikely to cause issues since performance.measure uses the most recent mark, but it could leave stale entries in the buffer.