@duffcloudservices/telemetry 0.2.0 → 0.3.0

package/src/composable.ts

@@ -1,8 +1,23 @@
-import { ApplicationInsights } from '@microsoft/applicationinsights-web'
+// TYPE-ONLY on purpose — this is the whole point of C-601's lazy path.
+//
+// A *value* import of the App Insights web SDK here folds the SDK into whatever
+// chunk imports this module, which for a site is the ENTRY chunk. Measured on the
+// bryans-handyman-solutions pilot (2026-08-11): adopting this package as published
+// moved 192,265B raw / 77,920B gzip of SDK off its own async chunk and onto the
+// entry chunk (+90.4% raw / +101.2% gzip), while the package's own code was only
+// +4.8KB of that. Total bytes barely moved — the SDK simply relocated onto the
+// critical path, defeating the sites' deliberate requestIdleCallback deferral.
+//
+// `import type` is erased by tsc/tsup, so it emits no runtime import at all. The
+// SDK is reached exactly once, through the dynamic `import()` in `loadSdk()`
+// below, which every bundler emits as a separate async chunk. Pinned by
+// `lazySdk.test.ts` — reintroducing a value import here turns that spec red.
+import type { ApplicationInsights } from '@microsoft/applicationinsights-web'
 import { computed, ref } from 'vue'
 
 import { DEFAULT_CLOUD_ROLE, createTelemetryConfig } from './config'
 import { captureJourneyFirstTouch, setJourneyIdentityResolver } from './journey'
+import { syntheticCaptureDetected } from './syntheticCapture'
 import type {
   TelemetryDependency,
   TelemetryEvent,
@@ -28,6 +43,139 @@ let appInsights: ApplicationInsights | null = null
 const isInitialized = ref(false)
 const initializationError = ref<string | null>(null)
 
+/**
+ * The in-flight lazy SDK load, or `null` when none is running.
+ *
+ * This is the single-init guard AND the "is a load in flight" signal the pre-init
+ * buffer keys off. Two concurrent `initialize()` callers — a `main.ts` boot and a
+ * component's `onMounted`, say — must produce ONE dynamic import and ONE
+ * `new ApplicationInsights(...)`, or the site gets two SDK instances racing the
+ * same connection string. Mirrors the guarded initializer the sites already run
+ * (kduff-homes `useTelemetry.ts` `initializationPromise`).
+ *
+ * Non-null also means "buffer, don't drop": see {@link bufferWhileLoading}.
+ */
+let initPromise: Promise<boolean> | null = null
+
+/** One already-built SDK call, replayed verbatim once the SDK arrives. */
+type PendingSdkCall = (instance: ApplicationInsights) => void
+
+/**
+ * Calls made after `initialize()` but before the lazy SDK chunk resolves.
+ *
+ * Without this, laziness would silently cost data: a site that calls
+ * `initialize()` and immediately reports a landing pageView or a `cta_click`
+ * would have both dropped by the `!isInitialized` guards, because the SDK is
+ * still in flight over the network. The site-local composables this package
+ * replaces DO drop those calls (bryans/kduff both early-return) — buffering is a
+ * strict improvement on the pattern being adopted, not a port of it.
+ *
+ * Payloads are built at CALL time, so `timestamp`, `page_path` and `referrer_host`
+ * describe the moment the event happened, not the moment the chunk landed. Order
+ * is preserved.
+ */
+const pendingSdkCalls: PendingSdkCall[] = []
+
+/**
+ * Bound on the buffer. A load that never settles (offline, blocked CDN, an
+ * ad-blocker eating the SDK chunk) must not grow an unbounded array for the rest
+ * of the session on a long-lived SPA. 100 is far above the handful of events a
+ * real pre-init window sees and far below anything that matters for memory.
+ */
+const PENDING_CALL_LIMIT = 100
+let warnedBufferFull = false
+
+/**
+ * Take ownership of a track* call while the SDK chunk is in flight.
+ *
+ * Returns `true` when this function has handled the call (buffered it, or
+ * deliberately dropped it because the buffer is full) and the caller must return.
+ * Returns `false` when no load is in flight — the caller then keeps its existing
+ * "not initialized" warn-and-drop behaviour, unchanged. That distinction is what
+ * stops an unconfigured site (never calls a successful `initialize()`) from
+ * accumulating a buffer nobody will ever drain.
+ */
+function bufferWhileLoading(call: PendingSdkCall): boolean {
+  if (!initPromise) return false
+
+  if (pendingSdkCalls.length >= PENDING_CALL_LIMIT) {
+    if (!warnedBufferFull) {
+      warnedBufferFull = true
+      console.warn(
+        `[telemetry] pre-init buffer full (${PENDING_CALL_LIMIT} calls) — dropping ` +
+          'telemetry until the Application Insights SDK chunk finishes loading. ' +
+          'If you see this, the SDK chunk is failing to load, not merely slow.',
+      )
+    }
+    return true
+  }
+
+  pendingSdkCalls.push(call)
+  return true
+}
+
+/** Replay everything buffered during the load, in order, then clear. */
+function drainPendingSdkCalls(instance: ApplicationInsights): void {
+  const calls = pendingSdkCalls.splice(0, pendingSdkCalls.length)
+  for (const call of calls) {
+    try {
+      call(instance)
+    } catch (error) {
+      console.error('Failed to replay buffered telemetry:', error)
+    }
+  }
+}
+
+/** Abandon anything buffered — the SDK is never arriving. */
+function discardPendingSdkCalls(): void {
+  pendingSdkCalls.length = 0
+}
+
+/**
+ * Load the App Insights web SDK constructor on demand.
+ *
+ * The ONE runtime reference to `@microsoft/applicationinsights-web` in this
+ * package. Kept as a bare dynamic `import()` (not wrapped in a variable specifier)
+ * so bundlers can statically see the dependency and emit it as its own async
+ * chunk — which is exactly the shape the sites hand-rolled and the shape this
+ * package existed to fold up.
+ */
+async function loadSdk(): Promise<typeof ApplicationInsights> {
+  const module = await import('@microsoft/applicationinsights-web')
+  return module.ApplicationInsights
+}
+
+/** Monotonic-ish clock for the pre-init page-timing pair. */
+function nowMs(): number {
+  return typeof performance !== 'undefined' && typeof performance.now === 'function'
+    ? performance.now()
+    : Date.now()
+}
+
+/**
+ * Pre-init `startTrackPage` timers, keyed by resolved page name.
+ *
+ * The SDK's own start/stop pair CANNOT be replayed faithfully after the fact: its
+ * internal timer would start at REPLAY time, so a page whose load straddled the
+ * lazy import would report a ~0ms duration. So a pair that straddles the load is
+ * timed here and replayed as the equivalent `trackPageView`.
+ *
+ * That is not an approximation — it is precisely what the SDK does internally.
+ * `AnalyticsPlugin.stopTrackPage` delegates to `_pageTracking.action`, which sets
+ * `properties.duration = duration.toString()` and calls `sendPageViewInternal`;
+ * `sendPageViewInternal` then derives `startTime` from `properties.duration` when
+ * no `startTime` is present (verified in applicationinsights-analytics-js 3.3.10,
+ * `dist-es5/JavaScriptSDK/AnalyticsPlugin.js`). Same wire shape, real duration —
+ * and, like the SDK, `duration` is left on the custom properties.
+ */
+const preInitPageTimings = new Map<string, number>()
+
+/** The name the SDK itself would use: the argument, else `document.title`. */
+function resolvePageName(name?: string): string {
+  if (typeof name === 'string') return name
+  return typeof document !== 'undefined' ? document.title : ''
+}
+
 // One-shot guards so we surface "App Insights is not configured" loudly in
 // DevTools the FIRST time the app tries to use it, but don't spam the console
 // for every subsequent trackEvent / trackPageView call. See web/ site-audit F2
@@ -144,6 +292,29 @@ function resolveAppVersion(explicit?: string): string {
  * pass plain values in) so this package stays portable and build-tool agnostic.
  * The shared App Insights config — including the `disablePageUnloadEvents:
  * ['unload']` bfcache/Lighthouse fix — comes from {@link createTelemetryConfig}.
+ *
+ * ## The SDK loads LAZILY (C-601)
+ *
+ * `initialize()` still returns `boolean` synchronously — "telemetry is enabled and
+ * the SDK load has started" — but the App Insights web SDK itself arrives through
+ * a dynamic `import()`, so a bundler emits it as its own async chunk instead of
+ * folding ~192KB raw / ~78KB gzip into the consumer's entry chunk. Adopting this
+ * package therefore no longer moves the SDK onto the critical path.
+ *
+ * Three things make that safe:
+ *
+ * 1. **Buffered, not dropped.** track* calls made between `initialize()` and the
+ *    chunk landing are queued with their call-time properties and replayed in
+ *    order (bounded at {@link PENDING_CALL_LIMIT}). The site-local composables this
+ *    package replaces dropped them.
+ * 2. **One init.** Concurrent `initialize()` callers share one `import()` and one
+ *    `new ApplicationInsights(...)` via {@link initPromise}.
+ * 3. **Guards stay synchronous.** `enableAutoRouteTracking` is resolved before the
+ *    `await`, so the C-288 double-count guard is armed for calls made during the
+ *    load, not only after it.
+ *
+ * `whenReady()` is there for the rare caller that must sequence work after the SDK
+ * exists. You should not need it to avoid losing events.
  */
 export function useTelemetry(options: TelemetryOptions = {}) {
   const cloudRole = options.cloudRole ?? DEFAULT_CLOUD_ROLE
@@ -213,10 +384,27 @@ export function useTelemetry(options: TelemetryOptions = {}) {
       // stored form submissions.
       captureJourneyFirstTouch()
 
+      // C-614: the post-deploy snapshot-capture step walks the LIVE site with
+      // real Chromium. Declining BEFORE the SDK is constructed means a capture
+      // pass emits no pageView, event or exception at all — every track* call
+      // below already no-ops while `isInitialized` is false. Checked after the
+      // journey snapshot above so that deliberately unconditional behaviour is
+      // left exactly as it was.
+      if (syntheticCaptureDetected()) {
+        return false
+      }
+
       if (isInitialized.value && appInsights) {
         return true
       }
 
+      // A load is already in flight (or already finished) — do NOT start a second
+      // one. Returning true keeps the caller's contract ("telemetry is on"); the
+      // awaitable answer is `whenReady()`.
+      if (initPromise) {
+        return true
+      }
+
       if (!isEnabled.value) {
         if (!warnedDisabled) {
           warnedDisabled = true
@@ -243,33 +431,66 @@ export function useTelemetry(options: TelemetryOptions = {}) {
       })
       // Remember whether the SDK is counting page views for us, so trackPageView()
       // can refuse to count them a second time.
+      //
+      // Resolved SYNCHRONOUSLY, before the lazy import, on purpose: the C-288
+      // double-count guard must be armed for the calls that arrive DURING the load,
+      // or a site with auto-route tracking on would buffer manual page views and
+      // then replay them into the duplicate the guard exists to prevent.
       autoRouteTrackingActive = resolvedConfig.enableAutoRouteTracking !== false
 
-      appInsights = new ApplicationInsights({ config: resolvedConfig })
-
-      appInsights.loadAppInsights()
-      appInsights.addTelemetryInitializer((envelope) => {
+      initPromise = (async (): Promise<boolean> => {
         try {
-          enrichTelemetryEnvelope(envelope as TelemetryEnvelope)
-        } catch (error) {
-          console.warn('Failed to add web telemetry context:', error)
-        }
+          const ApplicationInsightsCtor = await loadSdk()
 
-        return true
-      })
+          const instance = new ApplicationInsightsCtor({ config: resolvedConfig })
+          instance.loadAppInsights()
+          instance.addTelemetryInitializer((envelope) => {
+            try {
+              enrichTelemetryEnvelope(envelope as TelemetryEnvelope)
+            } catch (error) {
+              console.warn('Failed to add web telemetry context:', error)
+            }
+
+            return true
+          })
 
-      // Prefer the live SDK context over cookie parsing for the journey join
-      // key: the instance is authoritative, and it stays correct even if the
-      // cookies are blocked or renamed by a future SDK version.
-      setJourneyIdentityResolver(() => readSdkIdentity(appInsights))
+          // Published LAST, after the SDK is wired: `appInsights` is what every
+          // track* guard reads, so assigning it earlier would let a call slip
+          // through to a half-configured instance (no telemetry initializer, so no
+          // app_version / cloud role on the envelope).
+          appInsights = instance
 
-      isInitialized.value = true
-      initializationError.value = null
-      console.log('Application Insights initialized successfully')
+          // Prefer the live SDK context over cookie parsing for the journey join
+          // key: the instance is authoritative, and it stays correct even if the
+          // cookies are blocked or renamed by a future SDK version.
+          setJourneyIdentityResolver(() => readSdkIdentity(appInsights))
 
-      // Drain any conversion clicks captured before this transport existed, and stay
-      // attached for the rest of the session. See attachConversionCapture().
-      attachConversionCapture(trackEvent)
+          isInitialized.value = true
+          initializationError.value = null
+          console.log('Application Insights initialized successfully')
+
+          // Anything that fired between initialize() and this moment, in order.
+          drainPendingSdkCalls(instance)
+
+          // Drain any conversion clicks captured before this transport existed, and
+          // stay attached for the rest of the session. See attachConversionCapture().
+          attachConversionCapture(trackEvent)
+
+          return true
+        } catch (error) {
+          const errorMessage =
+            error instanceof Error ? error.message : 'Unknown initialization error'
+          initializationError.value = errorMessage
+          console.error('Failed to initialize Application Insights:', error)
+          // The SDK is not coming. Release the buffer rather than holding events
+          // for a drain that will never happen, and clear the in-flight marker so
+          // subsequent track* calls warn-and-drop instead of buffering forever.
+          discardPendingSdkCalls()
+          preInitPageTimings.clear()
+          initPromise = null
+          return false
+        }
+      })()
 
       return true
     } catch (error) {
@@ -281,8 +502,34 @@ export function useTelemetry(options: TelemetryOptions = {}) {
     }
   }
 
+  /**
+   * Resolves when the lazy App Insights chunk has finished loading (or failed).
+   *
+   * ADDITIVE — `initialize()` keeps its synchronous `boolean` return, so every
+   * existing caller (`web/src/main.ts`, the site adapters) is untouched. Use this
+   * when you genuinely need to sequence work after the SDK exists; you should not
+   * need it merely to avoid losing events, because calls made during the load are
+   * buffered and replayed.
+   *
+   * `false` means "no live SDK": telemetry is disabled, a synthetic capture pass
+   * declined it, `initialize()` was never called, or the chunk failed to load.
+   */
+  const whenReady = (): Promise<boolean> => {
+    if (isInitialized.value && appInsights) return Promise.resolve(true)
+    return initPromise ?? Promise.resolve(false)
+  }
+
   const trackEvent = (event: TelemetryEvent) => {
     if (!appInsights || !isInitialized.value) {
+      // Built here, not at drain time, so the timestamp/page_path describe when the
+      // event happened rather than when the SDK chunk landed.
+      const payload = {
+        name: event.name,
+        properties: buildEventProperties(event.properties),
+        measurements: event.measurements,
+      }
+      if (bufferWhileLoading((instance) => instance.trackEvent(payload))) return
+
       if (!warnedNotInitialized) {
         warnedNotInitialized = true
         console.warn(
@@ -318,11 +565,12 @@ export function useTelemetry(options: TelemetryOptions = {}) {
    * `useTelemetry({ enableAutoRouteTracking: false })`. One tracker, one count.
    */
   const trackPageView = (pageView?: TelemetryPageView) => {
-    if (!appInsights || !isInitialized.value) {
-      console.warn('Application Insights not initialized, skipping page view tracking')
-      return
-    }
-
+    // The double-count guard runs FIRST, before the init/buffer split. It is a
+    // question about CONFIG (is the SDK already counting routes?), not about load
+    // state, and `autoRouteTrackingActive` is resolved synchronously by
+    // initialize(). Checking it after the buffer would let manual page views queue
+    // during the load and then replay into the duplicate this guard exists to
+    // prevent (C-288: 52% of one site's page views).
     if (autoRouteTrackingActive && !pageView?.force) {
       if (!warnedDoubleCount) {
         warnedDoubleCount = true
@@ -337,24 +585,31 @@ export function useTelemetry(options: TelemetryOptions = {}) {
       return
     }
 
+    // Attach the full document.referrer (not just hostname) so we can
+    // attribute traffic sources in App Insights pageViews.
+    const referrer = typeof document !== 'undefined' ? (document.referrer ?? '') : ''
+    const payload = {
+      name:
+        pageView?.name ||
+        (typeof document !== 'undefined' ? document.title : undefined),
+      uri:
+        pageView?.uri ||
+        (typeof window !== 'undefined' ? window.location.href : undefined),
+      properties: buildEventProperties({
+        referrer,
+        ...pageView?.properties,
+      }),
+      measurements: pageView?.measurements,
+    }
+
+    if (!appInsights || !isInitialized.value) {
+      if (bufferWhileLoading((instance) => instance.trackPageView(payload))) return
+      console.warn('Application Insights not initialized, skipping page view tracking')
+      return
+    }
+
     try {
-      // Attach the full document.referrer (not just hostname) so we can
-      // attribute traffic sources in App Insights pageViews.
-      const referrer =
-        typeof document !== 'undefined' ? (document.referrer ?? '') : ''
-      appInsights.trackPageView({
-        name:
-          pageView?.name ||
-          (typeof document !== 'undefined' ? document.title : undefined),
-        uri:
-          pageView?.uri ||
-          (typeof window !== 'undefined' ? window.location.href : undefined),
-        properties: buildEventProperties({
-          referrer,
-          ...pageView?.properties,
-        }),
-        measurements: pageView?.measurements,
-      })
+      appInsights.trackPageView(payload)
     } catch (error) {
       console.error('Failed to track page view:', error)
     }
@@ -378,63 +633,75 @@ export function useTelemetry(options: TelemetryOptions = {}) {
   }
 
   const trackException = (exception: TelemetryException) => {
+    const payload = {
+      exception: exception.exception,
+      properties: buildEventProperties({
+        url: typeof window !== 'undefined' ? window.location.href : '',
+        userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+        ...exception.properties,
+      }),
+      measurements: exception.measurements,
+    }
+
     if (!appInsights || !isInitialized.value) {
+      // Exceptions are the calls that most need the buffer: a boot-time error is
+      // exactly the class of failure that fires while the SDK chunk is still in
+      // flight, and it is the class you least want silently dropped.
+      if (bufferWhileLoading((instance) => instance.trackException(payload))) return
       console.warn('Application Insights not initialized, skipping exception tracking')
       return
     }
 
     try {
-      appInsights.trackException({
-        exception: exception.exception,
-        properties: buildEventProperties({
-          url: typeof window !== 'undefined' ? window.location.href : '',
-          userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
-          ...exception.properties,
-        }),
-        measurements: exception.measurements,
-      })
+      appInsights.trackException(payload)
     } catch (error) {
       console.error('Failed to track exception:', error)
     }
   }
 
   const trackDependency = (dependency: TelemetryDependency) => {
+    const payload = {
+      id: `dep-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`,
+      name: dependency.name,
+      data: dependency.data,
+      duration: dependency.duration,
+      success: dependency.success,
+      responseCode: dependency.resultCode || 0,
+      properties: buildEventProperties(dependency.properties),
+      measurements: dependency.measurements,
+    }
+
     if (!appInsights || !isInitialized.value) {
+      if (bufferWhileLoading((instance) => instance.trackDependencyData(payload))) return
       console.warn('Application Insights not initialized, skipping dependency tracking')
       return
     }
 
     try {
-      appInsights.trackDependencyData({
-        id: `dep-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`,
-        name: dependency.name,
-        data: dependency.data,
-        duration: dependency.duration,
-        success: dependency.success,
-        responseCode: dependency.resultCode || 0,
-        properties: buildEventProperties(dependency.properties),
-        measurements: dependency.measurements,
-      })
+      appInsights.trackDependencyData(payload)
     } catch (error) {
       console.error('Failed to track dependency:', error)
     }
   }
 
   const trackMetric = (metric: TelemetryMetric) => {
+    const payload = {
+      name: metric.name,
+      average: metric.average,
+      sampleCount: metric.sampleCount,
+      min: metric.min,
+      max: metric.max,
+      properties: buildEventProperties(metric.properties),
+    }
+
     if (!appInsights || !isInitialized.value) {
+      if (bufferWhileLoading((instance) => instance.trackMetric(payload))) return
       console.warn('Application Insights not initialized, skipping metric tracking')
       return
     }
 
     try {
-      appInsights.trackMetric({
-        name: metric.name,
-        average: metric.average,
-        sampleCount: metric.sampleCount,
-        min: metric.min,
-        max: metric.max,
-        properties: buildEventProperties(metric.properties),
-      })
+      appInsights.trackMetric(payload)
     } catch (error) {
       console.error('Failed to track metric:', error)
     }
@@ -478,13 +745,25 @@ export function useTelemetry(options: TelemetryOptions = {}) {
   }
 
   const startTrackPage = (name?: string) => {
-    if (!appInsights || !isInitialized.value) return
+    // Redundancy first, for the same reason as trackPageView: it is a config
+    // question, answered synchronously, and it must hold for calls made during the
+    // lazy load too.
     if (manualPageTrackingIsRedundant()) return
 
-    try {
-      appInsights.startTrackPage(name)
-    } catch (error) {
-      console.error('Failed to start track page:', error)
+    if (appInsights && isInitialized.value) {
+      try {
+        appInsights.startTrackPage(name)
+      } catch (error) {
+        console.error('Failed to start track page:', error)
+      }
+      return
+    }
+
+    // Time it ourselves while the SDK chunk is in flight — see preInitPageTimings.
+    // Outside a load (initialize() never called, or it failed) this drops silently,
+    // exactly as before.
+    if (initPromise) {
+      preInitPageTimings.set(resolvePageName(name), nowMs())
     }
   }
 
@@ -494,14 +773,47 @@ export function useTelemetry(options: TelemetryOptions = {}) {
     properties?: Record<string, string>,
     measurements?: Record<string, number>,
   ) => {
-    if (!appInsights || !isInitialized.value) return
     if (manualPageTrackingIsRedundant()) return
 
-    try {
-      appInsights.stopTrackPage(name, url, buildEventProperties(properties), measurements)
-    } catch (error) {
-      console.error('Failed to stop track page:', error)
+    if (appInsights && isInitialized.value) {
+      try {
+        appInsights.stopTrackPage(name, url, buildEventProperties(properties), measurements)
+      } catch (error) {
+        console.error('Failed to stop track page:', error)
+      }
+      return
     }
+
+    if (!initPromise) return
+
+    const key = resolvePageName(name)
+    const startedAt = preInitPageTimings.get(key)
+    // No matching start means there is no timing to report — and inventing one
+    // would be worse than dropping it.
+    if (startedAt === undefined) return
+    preInitPageTimings.delete(key)
+
+    const duration = Math.max(0, Math.round(nowMs() - startedAt))
+    const payload = {
+      name: key,
+      uri: url ?? (typeof window !== 'undefined' ? window.location.href : undefined),
+      // `duration` as a STRING alongside the custom properties is the SDK's OWN
+      // encoding for a timed page view — `_pageTracking.action` does
+      // `properties.duration = duration.toString()` — and it is what
+      // `sendPageViewInternal` reads to back-date `startTime`.
+      //
+      // The cast is deliberate: `IPageViewTelemetry` declares `properties.duration`
+      // as `number`, which its own `stopTrackPage` path does not honour. Matching
+      // the runtime the collector actually parses beats matching a type that the
+      // emitting SDK contradicts.
+      properties: { ...buildEventProperties(properties), duration: String(duration) } as unknown as Record<
+        string,
+        number
+      >,
+      measurements,
+    }
+
+    bufferWhileLoading((instance) => instance.trackPageView(payload))
   }
 
   return {
@@ -509,6 +821,7 @@ export function useTelemetry(options: TelemetryOptions = {}) {
     isInitialized,
     initializationError,
     initialize,
+    whenReady,
     flush,
     startTrackPage,
     stopTrackPage,

package/src/index.ts

@@ -2,8 +2,12 @@
  * `@duffcloudservices/telemetry` — shared Azure Application Insights telemetry
  * for DCS Vue sites.
  *
- * - {@link useTelemetry} — the full composable (init + track* API). Statically
- *   imports the App Insights web SDK, so `initialize()` is synchronous.
+ * - {@link useTelemetry} — the full composable (init + track* API). Loads the App
+ *   Insights web SDK through a dynamic `import()` (C-601), so importing this entry
+ *   point costs the consumer NO SDK bytes on its entry chunk — the SDK becomes its
+ *   own async chunk, exactly as the hand-rolled site composables arranged. Calls
+ *   made while that chunk is in flight are buffered and replayed, so laziness does
+ *   not cost events.
  * - {@link createTelemetryConfig} — the shared App Insights config, with the
  *   `disablePageUnloadEvents: ['unload']` bfcache/Lighthouse fix baked into the
  *   default. Pure (no SDK import); also available SDK-free at
@@ -14,6 +18,7 @@
  *   telemetry boot.
  */
 export { useTelemetry, type TelemetryApi } from './composable'
+export { syntheticCaptureDetected, SYNTHETIC_CAPTURE_PARAMS } from './syntheticCapture'
 export {
   createTelemetryConfig,
   DEFAULT_CLOUD_ROLE,