ref(browser-utils): Move browser span-start APIs out of core

packages/browser-utils/src/ensureBrowserSpanStreaming.ts

@@ -0,0 +1,29 @@
+import type { Client } from '@sentry/core';
+import { getClient, hasSpanStreamingEnabled, spanStreamingIntegration } from '@sentry/core';
+
+/**
+ * The span streaming integration is only reachable from code that can actually start a span.
+ * `@sentry/browser`'s `init()` deliberately doesn't reference it, so error-only apps tree-shake the
+ * entire span streaming graph away without needing the `__SENTRY_TRACING__` flag. The guarded browser
+ * span-start APIs call this before starting a span.
+ */
+
+const clientsWithIntegration = new WeakSet<Client>();
+
+/**
+ * Lazily install the browser span streaming integration.
+ *
+ * Defaults to the current client; pass one explicitly from integration hooks, where the client being
+ * set up isn't necessarily the current one.
+ *
+ */
+export function ensureBrowserSpanStreaming(client: Client | undefined = getClient()): void {
+  // The `WeakSet` is an allocation optimization, not a semantic gate — `addIntegration()` is already
+  // idempotent by integration name, including against a user-supplied instance.
+  if (!client || clientsWithIntegration.has(client) || !hasSpanStreamingEnabled(client)) {
+    return;
+  }
+
+  clientsWithIntegration.add(client);
+  client.addIntegration(spanStreamingIntegration());
+}

packages/browser-utils/src/index.ts

@@ -9,6 +9,8 @@ export {
 
 export { addPerformanceEntries, startTrackingLongTasks, startTrackingLongAnimationFrames } from './performance/entries';
 
+export { startSpan, startInactiveSpan, startSpanManual } from './spanApi';
+
 export {
   addWebVitalsToSpan,
   // eslint-disable-next-line typescript/no-deprecated

packages/browser-utils/src/performance/interactions.ts

@@ -18,6 +18,7 @@ import {
 } from '@sentry/core';
 import { startIdleSpan } from '@sentry/core/browser';
 import { DEBUG_BUILD } from '../debug-build';
+import { ensureBrowserSpanStreaming } from '../ensureBrowserSpanStreaming';
 import { htmlTreeAsString } from '../htmlTreeAsString';
 import { addPerformanceInstrumentationHandler } from '../instrumentation/performanceObserver';
 import { isBotUserAgent } from '../isBotUserAgent';
@@ -66,6 +67,10 @@ const _interactionsIntegration = ((options: InteractionsOptions = {}) => {
         return;
       }
 
+      // Interaction spans are started through `startIdleSpan`, which - unlike the guarded `startSpan`
+      // APIs - does not install span streaming itself, so we ensure it here.
+      ensureBrowserSpanStreaming(client);
+
       const latestRoute: RouteInfo = { name: undefined, source: undefined };
       // The pageload/navigation span that is currently in progress, if any. Clicks that happen while one
       // is open are not turned into interaction spans, as they'd compete with the route span for children.

packages/browser-utils/src/performance/utils.ts

@@ -1,6 +1,6 @@
 import type { SentrySpan, Span, SpanTimeInput, StartSpanOptions } from '@sentry/core';
 import { spanToStaticSpanJSON, withActiveSpan } from '@sentry/core';
-import { startInactiveSpan } from '@sentry/core/browser';
+import { startInactiveSpan } from '../spanApi';
 import { WINDOW } from '../types';
 
 /**

packages/core/src/tracing/browserSpanApi.ts → packages/browser-utils/src/spanApi.ts

@@ -1,14 +1,14 @@
-import type { Client } from '../client';
-import { getClient } from '../currentScopes';
-import { spanStreamingIntegration } from '../integrations/spanStreaming';
-import type { Span } from '../types/span';
-import type { StartSpanOptions } from '../types/startSpanOptions';
-import { hasSpanStreamingEnabled } from './spans/hasSpanStreamingEnabled';
+import type { Span, StartSpanOptions } from '@sentry/core';
+/* oxlint-disable sdk/no-unguarded-span-apis -- This module IS the guarded browser variant: each wrapper
+   installs `spanStreamingIntegration` via `ensureBrowserSpanStreaming` before delegating to the
+   plain core API, which is exactly what browser-facing code is meant to go through. */
 import {
   startInactiveSpan as coreStartInactiveSpan,
   startSpan as coreStartSpan,
   startSpanManual as coreStartSpanManual,
-} from './trace';
+} from '@sentry/core';
+/* oxlint-enable sdk/no-unguarded-span-apis */
+import { ensureBrowserSpanStreaming } from './ensureBrowserSpanStreaming';
 
 /**
  * Browser variants of the span-start APIs.
@@ -19,34 +19,13 @@ import {
  * the `__SENTRY_TRACING__` flag.
  */
 
-const clientsWithIntegration = new WeakSet<Client>();
-
-/**
- * Lazily install the browser span streaming integration.
- *
- * Defaults to the current client; pass one explicitly from integration hooks, where the client being
- * set up isn't necessarily the current one.
- *
- * @internal
- */
-export function _INTERNAL_ensureBrowserSpanStreaming(client: Client | undefined = getClient()): void {
-  // The `WeakSet` is an allocation optimization, not a semantic gate — `addIntegration()` is already
-  // idempotent by integration name, including against a user-supplied instance.
-  if (!client || clientsWithIntegration.has(client) || !hasSpanStreamingEnabled(client)) {
-    return;
-  }
-
-  clientsWithIntegration.add(client);
-  client.addIntegration(spanStreamingIntegration());
-}
-
 /**
  * Wraps a function with a span and finishes the span after the function is done.
  *
  * See {@link startSpan} in `@sentry/core` for details.
  */
 export function startSpan<T>(options: StartSpanOptions, callback: (span: Span) => T): T {
-  _INTERNAL_ensureBrowserSpanStreaming();
+  ensureBrowserSpanStreaming();
   return coreStartSpan(options, callback);
 }
 
@@ -56,7 +35,7 @@ export function startSpan<T>(options: StartSpanOptions, callback: (span: Span) =
  * See {@link startSpanManual} in `@sentry/core` for details.
  */
 export function startSpanManual<T>(options: StartSpanOptions, callback: (span: Span, finish: () => void) => T): T {
-  _INTERNAL_ensureBrowserSpanStreaming();
+  ensureBrowserSpanStreaming();
   return coreStartSpanManual(options, callback);
 }
 
@@ -66,6 +45,6 @@ export function startSpanManual<T>(options: StartSpanOptions, callback: (span: S
  * See {@link startInactiveSpan} in `@sentry/core` for details.
  */
 export function startInactiveSpan(options: StartSpanOptions): Span {
-  _INTERNAL_ensureBrowserSpanStreaming();
+  ensureBrowserSpanStreaming();
   return coreStartInactiveSpan(options);
 }

packages/browser-utils/src/web-vitals/spans.ts

@@ -13,7 +13,7 @@ import {
   spanToJSON,
   timestampInSeconds,
 } from '@sentry/core';
-import { startInactiveSpan } from '@sentry/core/browser';
+import { startInactiveSpan } from '../spanApi';
 import { DEBUG_BUILD } from '../debug-build';
 import { htmlTreeAsString } from '../htmlTreeAsString';
 import { WINDOW } from '../types';