From a834536387e22c80ff2ac3f8ed980150efead1f1 Mon Sep 17 00:00:00 2001
From: Lukas Stracke <lukas.stracke@sentry.io>
Date: Wed, 12 Aug 2026 15:10:56 +0200
Subject: [PATCH 1/5] ref(browser): Tree-shake span streaming out of error-only
 bundles

`init()` no longer pushes `spanStreamingIntegration()`. That single
reference was the only thing retaining `SpanBuffer`, `captureSpan`,
`estimateSize` and `scopeContextAttributes` in every browser bundle,
including bundles for apps that never use tracing.

Instead, browser-facing packages import their span-start APIs from
`@sentry/core/browser`, which installs the integration on the client
before the first span starts. A span can only end if it was started, so
the `afterSpanEnd` listener is always registered in time.

`init` alone drops from 28.52 kB to 26.95 kB gzipped, within 0.1 kB of
the `__SENTRY_TRACING__: false` floor. Tracing users pay nothing extra.

Both variants share their names, so a stray plain import compiles fine
and silently stops sending spans. `sdk/no-unguarded-span-apis` is the
only thing that catches that, hence it lands here rather than later.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .oxlintrc.base.json                           |   9 ++
 .size-limit.js                                |  11 +-
 .../browser-utils/src/performance/utils.ts    |   3 +-
 .../browser-utils/src/web-vitals/spans.ts     |   2 +-
 .../test/web-vitals/spans.test.ts             |  69 +++++----
 .../integrations/fetchStreamPerformance.ts    |   2 +-
 packages/browser/src/sdk.ts                   |  13 +-
 .../src/tracing/browserTracingIntegration.ts  |   6 +
 packages/browser/test/sdk.test.ts             |  36 ++---
 .../test/tracing/spanStreamingWiring.test.ts  | 114 +++++++++++++++
 packages/effect/src/tracer.ts                 |  12 +-
 packages/effect/test/layer.test.ts            |   8 +-
 packages/effect/test/tracer.test.ts           |  13 +-
 packages/eslint-plugin-sdk/src/index.js       |   1 +
 .../src/rules/no-unguarded-span-apis.js       | 121 ++++++++++++++++
 .../lib/rules/no-unguarded-span-apis.test.ts  | 131 ++++++++++++++++++
 packages/nextjs/src/client/index.ts           |   6 +-
 packages/nextjs/src/index.types.ts            |   6 +
 .../src/client/createClientInstrumentation.ts |   2 +-
 .../createClientInstrumentation.test.ts       |  40 +++---
 packages/svelte/src/performance.ts            |   3 +-
 packages/sveltekit/src/client/load.ts         |   2 +-
 packages/sveltekit/test/client/load.test.ts   |   4 +-
 23 files changed, 500 insertions(+), 114 deletions(-)
 create mode 100644 packages/browser/test/tracing/spanStreamingWiring.test.ts
 create mode 100644 packages/eslint-plugin-sdk/src/rules/no-unguarded-span-apis.js
 create mode 100644 packages/eslint-plugin-sdk/test/lib/rules/no-unguarded-span-apis.test.ts

diff --git a/.oxlintrc.base.json b/.oxlintrc.base.json
index 7c9302092965..9db79820a5e8 100644
--- a/.oxlintrc.base.json
+++ b/.oxlintrc.base.json
@@ -68,6 +68,15 @@
         "sdk/no-unfiltered-url-attributes": "error"
       }
     },
+    {
+      // The rule itself decides which files are browser-facing (see `no-unguarded-span-apis.js`);
+      // oxlint resolves `files` globs relative to each package's own config, so scoping it to
+      // individual packages here is not possible.
+      "files": ["**/src/**/*.ts", "**/src/**/*.tsx", "**/addon/**/*.ts"],
+      "rules": {
+        "sdk/no-unguarded-span-apis": "error"
+      }
+    },
     {
       "files": ["**/*.ts", "**/*.tsx", "**/*.d.ts"],
       "rules": {
diff --git a/.size-limit.js b/.size-limit.js
index 30422d018896..ad6e4daca85e 100644
--- a/.size-limit.js
+++ b/.size-limit.js
@@ -3,12 +3,15 @@ const nodePrefixedBuiltinModules = builtinModules.map(m => `node:${m}`);
 
 module.exports = [
   // Browser SDK (ESM)
+  // The three `init`-only entries below are kept deliberately tight (< 1 KB headroom): an `init`
+  // that references `spanStreamingIntegration` again - directly or through a transitive import -
+  // costs ~1.6 KB here and would otherwise land unnoticed.
   {
     name: '@sentry/browser',
     path: 'packages/browser/build/npm/esm/prod/index.js',
     import: createImport('init'),
     gzip: true,
-    limit: '36 KB',
+    limit: '29.5 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
@@ -16,7 +19,7 @@ module.exports = [
     path: 'packages/browser/build/npm/esm/prod/index.js',
     import: createImport('init'),
     gzip: true,
-    limit: '34 KB',
+    limit: '28 KB',
     disablePlugins: ['@size-limit/esbuild'],
     modifyWebpackConfig: function (config) {
       const webpack = require('webpack');
@@ -36,11 +39,13 @@ module.exports = [
     },
   },
   {
+    // Now that `init` no longer pulls in span streaming, this entry is within ~0.1 KB of the entry
+    // above. It stays as the floor: if the two ever diverge again, tracing code leaked back in.
     name: '@sentry/browser - with treeshaking flags tracing without tracing',
     path: 'packages/browser/build/npm/esm/prod/index.js',
     import: createImport('init'),
     gzip: true,
-    limit: '32 KB',
+    limit: '28 KB',
     disablePlugins: ['@size-limit/esbuild'],
     modifyWebpackConfig: function (config) {
       const webpack = require('webpack');
diff --git a/packages/browser-utils/src/performance/utils.ts b/packages/browser-utils/src/performance/utils.ts
index 6a089c762fd2..a9a9759e7ed5 100644
--- a/packages/browser-utils/src/performance/utils.ts
+++ b/packages/browser-utils/src/performance/utils.ts
@@ -1,5 +1,6 @@
 import type { SentrySpan, Span, SpanTimeInput, StartSpanOptions } from '@sentry/core';
-import { spanToStaticSpanJSON, startInactiveSpan, withActiveSpan } from '@sentry/core';
+import { spanToStaticSpanJSON, withActiveSpan } from '@sentry/core';
+import { startInactiveSpan } from '@sentry/core/browser';
 import { WINDOW } from '../types';
 
 /**
diff --git a/packages/browser-utils/src/web-vitals/spans.ts b/packages/browser-utils/src/web-vitals/spans.ts
index f6ad68b7ec1c..b0a42383bb03 100644
--- a/packages/browser-utils/src/web-vitals/spans.ts
+++ b/packages/browser-utils/src/web-vitals/spans.ts
@@ -11,9 +11,9 @@ import {
   SEMANTIC_ATTRIBUTE_SENTRY_OP,
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   spanToJSON,
-  startInactiveSpan,
   timestampInSeconds,
 } from '@sentry/core';
+import { startInactiveSpan } from '@sentry/core/browser';
 import { DEBUG_BUILD } from '../debug-build';
 import { htmlTreeAsString } from '../htmlTreeAsString';
 import { WINDOW } from '../types';
diff --git a/packages/browser-utils/test/web-vitals/spans.test.ts b/packages/browser-utils/test/web-vitals/spans.test.ts
index d23949c3307d..17f848364c3e 100644
--- a/packages/browser-utils/test/web-vitals/spans.test.ts
+++ b/packages/browser-utils/test/web-vitals/spans.test.ts
@@ -1,4 +1,5 @@
 import * as SentryCore from '@sentry/core';
+import * as SentryCoreBrowser from '@sentry/core/browser';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { htmlTreeAsString } from '../../src/htmlTreeAsString';
 import * as inpModule from '../../src/web-vitals/inp';
@@ -20,13 +21,21 @@ vi.mock('@sentry/core', async () => {
     timestampInSeconds: vi.fn(),
     getCurrentScope: vi.fn(),
     getClient: vi.fn(),
-    startInactiveSpan: vi.fn(),
     getActiveSpan: vi.fn(),
     getRootSpan: vi.fn(),
     spanToJSON: vi.fn(),
   };
 });
 
+// `startInactiveSpan` comes from `@sentry/core/browser`, not the root entry - see `browserSpanApi.ts`.
+vi.mock('@sentry/core/browser', async () => {
+  const actual = await vi.importActual('@sentry/core/browser');
+  return {
+    ...actual,
+    startInactiveSpan: vi.fn(),
+  };
+});
+
 vi.mock('../../src/htmlTreeAsString', () => ({
   htmlTreeAsString: vi.fn(),
 }));
@@ -62,7 +71,7 @@ describe('_emitWebVitalSpan', () => {
 
   beforeEach(() => {
     vi.mocked(SentryCore.getCurrentScope).mockReturnValue(mockScope as any);
-    vi.mocked(SentryCore.startInactiveSpan).mockReturnValue(mockSpan as any);
+    vi.mocked(SentryCoreBrowser.startInactiveSpan).mockReturnValue(mockSpan as any);
     vi.mocked(SentryCore.spanToJSON).mockReturnValue({ attributes: {} } as any);
     vi.mocked(SentryCore.getClient).mockReturnValue({ getIntegrationByName: () => undefined } as any);
   });
@@ -81,7 +90,7 @@ describe('_emitWebVitalSpan', () => {
       startTime: 1.5,
     });
 
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith({
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith({
       name: 'Test Vital',
       attributes: {
         'sentry.origin': 'auto.http.browser.lcp',
@@ -96,7 +105,7 @@ describe('_emitWebVitalSpan', () => {
     });
 
     // No standalone flag
-    expect(SentryCore.startInactiveSpan).not.toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).not.toHaveBeenCalledWith(
       expect.objectContaining({ experimental: expect.anything() }),
     );
 
@@ -114,7 +123,7 @@ describe('_emitWebVitalSpan', () => {
       standalone: true,
     });
 
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({ experimental: { standalone: true } }),
     );
   });
@@ -134,7 +143,7 @@ describe('_emitWebVitalSpan', () => {
       standalone: true,
     });
 
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         attributes: expect.objectContaining({
           'sentry.replay_id': 'replay-123',
@@ -159,7 +168,7 @@ describe('_emitWebVitalSpan', () => {
       standalone: true,
     });
 
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         attributes: expect.objectContaining({ 'sentry._internal.replay_is_buffering': true }),
       }),
@@ -180,7 +189,7 @@ describe('_emitWebVitalSpan', () => {
       startTime: 1.5,
     });
 
-    const attributes = vi.mocked(SentryCore.startInactiveSpan).mock.calls[0]![0].attributes!;
+    const attributes = vi.mocked(SentryCoreBrowser.startInactiveSpan).mock.calls[0]![0].attributes!;
     expect(attributes['sentry.replay_id']).toBeUndefined();
   });
 
@@ -200,7 +209,7 @@ describe('_emitWebVitalSpan', () => {
       startTime: 1.0,
     });
 
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         attributes: expect.objectContaining({
           'sentry.pageload.span_id': 'abc123',
@@ -226,7 +235,7 @@ describe('_emitWebVitalSpan', () => {
       startTime: 1.0,
     });
 
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         attributes: expect.not.objectContaining({
           'sentry.pageload.span_id': expect.anything(),
@@ -246,7 +255,7 @@ describe('_emitWebVitalSpan', () => {
       startTime: 1.0,
     });
 
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         attributes: expect.objectContaining({
           'browser.web_vital.cls.report_event': 'pagehide',
@@ -266,7 +275,7 @@ describe('_emitWebVitalSpan', () => {
       startTime: 1.0,
     });
 
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         attributes: expect.objectContaining({
           'custom.attr': 'value',
@@ -276,7 +285,7 @@ describe('_emitWebVitalSpan', () => {
   });
 
   it('handles when startInactiveSpan returns undefined', () => {
-    vi.mocked(SentryCore.startInactiveSpan).mockReturnValue(undefined as any);
+    vi.mocked(SentryCoreBrowser.startInactiveSpan).mockReturnValue(undefined as any);
 
     expect(() => {
       _emitWebVitalSpan({
@@ -306,7 +315,7 @@ describe('_sendLcpSpan', () => {
     vi.mocked(SentryCore.getCurrentScope).mockReturnValue(mockScope as any);
     vi.mocked(SentryCore.browserPerformanceTimeOrigin).mockReturnValue(1000);
     vi.mocked(htmlTreeAsString).mockImplementation((node: any) => `<${node?.tagName || 'div'}>`);
-    vi.mocked(SentryCore.startInactiveSpan).mockReturnValue(mockSpan as any);
+    vi.mocked(SentryCoreBrowser.startInactiveSpan).mockReturnValue(mockSpan as any);
     vi.mocked(SentryCore.spanToJSON).mockReturnValue({
       attributes: { 'sentry.op': 'pageload' },
     } as any);
@@ -331,7 +340,7 @@ describe('_sendLcpSpan', () => {
 
     _sendLcpSpan(250, mockEntry, mockPageloadSpan as any, 'pagehide');
 
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         name: '<img>',
         attributes: expect.objectContaining({
@@ -361,7 +370,7 @@ describe('_sendLcpSpan', () => {
   it('sends a streamed LCP span without entry data', () => {
     _sendLcpSpan(250, undefined);
 
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         name: 'Largest contentful paint',
         startTime: 1, // timeOrigin: 1000 / 1000
@@ -373,7 +382,7 @@ describe('_sendLcpSpan', () => {
     _sendLcpSpan(0, undefined);
     _sendLcpSpan(MAX_PLAUSIBLE_LCP_DURATION + 1, undefined);
 
-    expect(SentryCore.startInactiveSpan).not.toHaveBeenCalled();
+    expect(SentryCoreBrowser.startInactiveSpan).not.toHaveBeenCalled();
   });
 });
 
@@ -393,7 +402,7 @@ describe('_sendClsSpan', () => {
     vi.mocked(SentryCore.browserPerformanceTimeOrigin).mockReturnValue(1000);
     vi.mocked(SentryCore.timestampInSeconds).mockReturnValue(1.5);
     vi.mocked(htmlTreeAsString).mockImplementation((node: any) => `<${node?.tagName || 'div'}>`);
-    vi.mocked(SentryCore.startInactiveSpan).mockReturnValue(mockSpan as any);
+    vi.mocked(SentryCoreBrowser.startInactiveSpan).mockReturnValue(mockSpan as any);
     vi.mocked(SentryCore.spanToJSON).mockReturnValue({
       attributes: { 'sentry.op': 'pageload' },
     } as any);
@@ -429,7 +438,7 @@ describe('_sendClsSpan', () => {
 
     _sendClsSpan(0.1, mockEntry, mockPageloadSpan as any, 'navigation');
 
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         name: '<div>',
         attributes: expect.objectContaining({
@@ -451,7 +460,7 @@ describe('_sendClsSpan', () => {
     _sendClsSpan(0, undefined);
 
     expect(SentryCore.timestampInSeconds).toHaveBeenCalled();
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         name: 'Layout shift',
         startTime: 1.5,
@@ -475,7 +484,7 @@ describe('_sendInpSpan', () => {
     vi.mocked(SentryCore.getCurrentScope).mockReturnValue(mockScope as any);
     vi.mocked(SentryCore.browserPerformanceTimeOrigin).mockReturnValue(1000);
     vi.mocked(htmlTreeAsString).mockReturnValue('<button>');
-    vi.mocked(SentryCore.startInactiveSpan).mockReturnValue(mockSpan as any);
+    vi.mocked(SentryCoreBrowser.startInactiveSpan).mockReturnValue(mockSpan as any);
     vi.mocked(SentryCore.getActiveSpan).mockReturnValue(undefined);
     vi.mocked(SentryCore.spanToJSON).mockReturnValue({ attributes: {} } as any);
   });
@@ -498,7 +507,7 @@ describe('_sendInpSpan', () => {
     _sendInpSpan(120, mockEntry);
 
     // startTime = (1000 + 500) / 1000 = 1.5
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         name: '<button>',
         startTime: 1.5,
@@ -529,7 +538,7 @@ describe('_sendInpSpan', () => {
 
     _sendInpSpan(80, mockEntry);
 
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         attributes: expect.objectContaining({
           'sentry.op': 'ui.interaction.press',
@@ -561,7 +570,7 @@ describe('_sendInpSpan', () => {
 
     expect(inpModule.getCachedInteractionContext).toHaveBeenCalledWith(42);
 
-    expect(SentryCore.startInactiveSpan).toHaveBeenCalledWith(
+    expect(SentryCoreBrowser.startInactiveSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         name: 'body > CachedButton',
         attributes: expect.objectContaining({
@@ -593,7 +602,7 @@ describe('trackInpAsSpan', () => {
     vi.mocked(SentryCore.browserPerformanceTimeOrigin).mockReturnValue(1000);
     vi.mocked(SentryCore.getCurrentScope).mockReturnValue(mockScope as any);
     vi.mocked(SentryCore.getActiveSpan).mockReturnValue(undefined);
-    vi.mocked(SentryCore.startInactiveSpan).mockReturnValue({ end: vi.fn() } as any);
+    vi.mocked(SentryCoreBrowser.startInactiveSpan).mockReturnValue({ end: vi.fn() } as any);
     vi.mocked(SentryCore.spanToJSON).mockReturnValue({ attributes: {} } as any);
     vi.mocked(htmlTreeAsString).mockReturnValue('<button>');
     vi.spyOn(inpModule, 'getCachedInteractionContext').mockReturnValue(undefined);
@@ -611,7 +620,7 @@ describe('trackInpAsSpan', () => {
     trackInpAsSpan(streamingClient);
     inpCallback({ metric: validMetric });
 
-    const call = vi.mocked(SentryCore.startInactiveSpan).mock.calls[0]![0];
+    const call = vi.mocked(SentryCoreBrowser.startInactiveSpan).mock.calls[0]![0];
     expect(call.experimental).toBeUndefined();
     expect(call.attributes?.['sentry.op']).toBe('ui.interaction.click');
   });
@@ -621,25 +630,25 @@ describe('trackInpAsSpan', () => {
     trackInpAsSpan(staticClient);
     inpCallback({ metric: validMetric });
 
-    const call = vi.mocked(SentryCore.startInactiveSpan).mock.calls[0]![0];
+    const call = vi.mocked(SentryCoreBrowser.startInactiveSpan).mock.calls[0]![0];
     expect(call.experimental).toEqual({ standalone: true });
   });
 
   it('ignores INP metrics without a value', () => {
     trackInpAsSpan(streamingClient);
     inpCallback({ metric: { value: null, entries: [] } });
-    expect(SentryCore.startInactiveSpan).not.toHaveBeenCalled();
+    expect(SentryCoreBrowser.startInactiveSpan).not.toHaveBeenCalled();
   });
 
   it('ignores implausibly long INP durations', () => {
     trackInpAsSpan(streamingClient);
     inpCallback({ metric: { value: (inpModule.MAX_PLAUSIBLE_INP_DURATION + 1) * 1000, entries: validMetric.entries } });
-    expect(SentryCore.startInactiveSpan).not.toHaveBeenCalled();
+    expect(SentryCoreBrowser.startInactiveSpan).not.toHaveBeenCalled();
   });
 
   it('ignores INP metrics without a matching interaction entry', () => {
     trackInpAsSpan(streamingClient);
     inpCallback({ metric: { value: 120, entries: [{ name: 'scroll', duration: 120 }] } });
-    expect(SentryCore.startInactiveSpan).not.toHaveBeenCalled();
+    expect(SentryCoreBrowser.startInactiveSpan).not.toHaveBeenCalled();
   });
 });
diff --git a/packages/browser/src/integrations/fetchStreamPerformance.ts b/packages/browser/src/integrations/fetchStreamPerformance.ts
index ce8ec59782d1..746e578fc9b6 100644
--- a/packages/browser/src/integrations/fetchStreamPerformance.ts
+++ b/packages/browser/src/integrations/fetchStreamPerformance.ts
@@ -8,10 +8,10 @@ import {
   parseStringToURLObject,
   SEMANTIC_ATTRIBUTE_SENTRY_OP,
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
-  startInactiveSpan,
   stripDataUrlContent,
   filterCollectedUrl,
 } from '@sentry/core';
+import { startInactiveSpan } from '@sentry/core/browser';
 
 const responseToStreamSpan = new WeakMap<object, Span>();
 const responseToFallbackTimeout = new WeakMap<object, ReturnType<typeof setTimeout>>();
diff --git a/packages/browser/src/sdk.ts b/packages/browser/src/sdk.ts
index 61584ef961b0..c819c2e132ba 100644
--- a/packages/browser/src/sdk.ts
+++ b/packages/browser/src/sdk.ts
@@ -7,7 +7,6 @@ import {
   getIntegrationsToSetup,
   initAndBind,
   setNormalizeStringifier,
-  spanStreamingIntegration,
   stackParserFromStackParserOptions,
 } from '@sentry/core/browser';
 import type { BrowserClientOptions, BrowserOptions } from './client';
@@ -25,8 +24,6 @@ import { makeFetchTransport } from './transports/fetch';
 import { normalizeStringifyValue } from './normalizeStringifyValue';
 import { checkAndWarnIfIsEmbeddedBrowserExtension } from './utils/detectBrowserExtension';
 
-declare const __SENTRY_TRACING__: boolean;
-
 /** Get the default integrations for the browser SDK. */
 export function getDefaultIntegrations(_options: Options): Integration[] {
   /**
@@ -116,13 +113,9 @@ export function init(options: BrowserOptions = {}): Client | undefined {
     defaultIntegrations,
   });
 
-  if (
-    (typeof __SENTRY_TRACING__ === 'undefined' || __SENTRY_TRACING__) &&
-    options.traceLifecycle !== 'static' &&
-    !integrations.some(integration => integration.name === 'SpanStreaming')
-  ) {
-    integrations.push(spanStreamingIntegration());
-  }
+  // `spanStreamingIntegration` is deliberately not added here: referencing it from `init()` would
+  // pull the entire span streaming graph into every bundle, including error-only ones. Instead the
+  // span-start APIs in `@sentry/core/browser` install it on first use — see `browserSpanApi.ts`.
 
   const clientOptions: BrowserClientOptions = {
     ...options,
diff --git a/packages/browser/src/tracing/browserTracingIntegration.ts b/packages/browser/src/tracing/browserTracingIntegration.ts
index dc174f7f21b5..34bb5f9745db 100644
--- a/packages/browser/src/tracing/browserTracingIntegration.ts
+++ b/packages/browser/src/tracing/browserTracingIntegration.ts
@@ -9,6 +9,7 @@ import type {
   TransactionSource,
 } from '@sentry/core/browser';
 import {
+  _INTERNAL_ensureBrowserSpanStreaming,
   addNonEnumerableProperty,
   browserPerformanceTimeOrigin,
   consoleSandbox,
@@ -616,6 +617,11 @@ export const browserTracingIntegration = ((options: Partial<BrowserTracingOption
         return;
       }
 
+      // Technically, every startSpan call already ensures that `spanStreamingIntegration` is installed,
+      // but we do it here anyway for the edge case that users disabled pageload and navigation spans and
+      // purely rely on manual startSpan calls.
+      _INTERNAL_ensureBrowserSpanStreaming(client);
+
       // Auto-register webVitalsIntegration if the user hasn't added one. We do this in
       // afterAllSetup so that a user-provided webVitalsIntegration - which may be ordered after
       // browserTracingIntegration in the integrations array - has already been installed.
diff --git a/packages/browser/test/sdk.test.ts b/packages/browser/test/sdk.test.ts
index 744025bc1b1d..f96a78311f1c 100644
--- a/packages/browser/test/sdk.test.ts
+++ b/packages/browser/test/sdk.test.ts
@@ -61,25 +61,16 @@ describe('init', () => {
     expect(optionsPassed?.integrations.length).toBeGreaterThan(0);
   });
 
-  it('installs spanStreamingIntegration by default', () => {
+  // `init` must not reference `spanStreamingIntegration`: that reference alone is what keeps the
+  // whole span streaming graph in error-only bundles. It is installed lazily by the span-start APIs
+  // instead - see `_INTERNAL_ensureBrowserSpanStreaming`.
+  it.each([
+    ['default integrations', undefined],
+    ['default integrations disabled', false as const],
+  ])('does not install spanStreamingIntegration with %s', (_, defaultIntegrations) => {
     // @ts-expect-error this is fine for testing
     const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
-    const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: undefined });
-
-    init(options);
-
-    const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
-    expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
-  });
-
-  it('does not install spanStreamingIntegration when traceLifecycle is static', () => {
-    // @ts-expect-error this is fine for testing
-    const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
-    const options = getDefaultBrowserOptions({
-      dsn: PUBLIC_DSN,
-      defaultIntegrations: undefined,
-      traceLifecycle: 'static',
-    });
+    const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations });
 
     init(options);
 
@@ -99,17 +90,6 @@ describe('init', () => {
     expect(DEFAULT_INTEGRATIONS[1]!.setupOnce as Mock).toHaveBeenCalledTimes(0);
   });
 
-  it('installs spanStreamingIntegration with defaultIntegrations disabled', () => {
-    // @ts-expect-error this is fine for testing
-    const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
-    const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations: false });
-
-    init(options);
-
-    const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
-    expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(true);
-  });
-
   it('installs merged default integrations, with overrides provided through options', () => {
     const DEFAULT_INTEGRATIONS = [
       new MockIntegration('MockIntegration 1.1'),
diff --git a/packages/browser/test/tracing/spanStreamingWiring.test.ts b/packages/browser/test/tracing/spanStreamingWiring.test.ts
new file mode 100644
index 000000000000..9745a3a8b811
--- /dev/null
+++ b/packages/browser/test/tracing/spanStreamingWiring.test.ts
@@ -0,0 +1,114 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import type { Client, Envelope } from '@sentry/core/browser';
+import {
+  createTransport,
+  getMainCarrier,
+  resolvedSyncPromise,
+  startInactiveSpan,
+  startSpan,
+} from '@sentry/core/browser';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { BrowserOptions } from '../../src';
+import { browserTracingIntegration, init } from '../../src';
+
+// These tests cover the wiring between `init`, the span-start APIs and `spanStreamingIntegration`.
+// The integration itself is unit tested in `@sentry/core`; what is easy to break - and what nothing
+// else covers - is that it gets installed at all now that `init` no longer references it.
+
+function initSdk(options: Partial<BrowserOptions> = {}): Client | undefined {
+  return init({
+    dsn: 'https://username@domain/123',
+    tracesSampleRate: 1,
+    transport: () => createTransport({ recordDroppedEvent: () => undefined }, () => resolvedSyncPromise({})),
+    ...options,
+  });
+}
+
+function recordEnvelopes(client: Client | undefined): Envelope[] {
+  const envelopes: Envelope[] = [];
+  vi.spyOn(client!, 'sendEnvelope').mockImplementation(envelope => {
+    envelopes.push(envelope);
+    return resolvedSyncPromise({});
+  });
+  return envelopes;
+}
+
+/** Pulls the serialized spans out of the span v2 container items of the recorded envelopes. */
+function getStreamedSpans(envelopes: Envelope[]): Array<{ name?: string; is_segment?: boolean }> {
+  return envelopes
+    .flatMap(([, items]) => items)
+    .filter(([itemHeader]) => itemHeader.type === 'span')
+    .flatMap(([, payload]) => (payload as { items: Array<{ name?: string; is_segment?: boolean }> }).items);
+}
+
+describe('span streaming wiring', () => {
+  beforeEach(() => {
+    getMainCarrier().__SENTRY__ = undefined;
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('`init` alone does not install the integration', () => {
+    const client = initSdk();
+
+    expect(client?.getIntegrationByName('SpanStreaming')).toBeUndefined();
+  });
+
+  it('does not install the integration for `traceLifecycle: "static"`, even once a span starts', () => {
+    const client = initSdk({ traceLifecycle: 'static' });
+
+    startSpan({ name: 'test' }, () => {});
+
+    expect(client?.getIntegrationByName('SpanStreaming')).toBeUndefined();
+  });
+
+  it.each([
+    ['startSpan', () => startSpan({ name: 'test' }, () => {})],
+    ['startInactiveSpan', () => startInactiveSpan({ name: 'test' }).end()],
+  ])('installs the integration when the first span is started via %s', (_, startTestSpan) => {
+    const client = initSdk();
+    expect(client?.getIntegrationByName('SpanStreaming')).toBeUndefined();
+
+    startTestSpan();
+
+    expect(client?.getIntegrationByName('SpanStreaming')).toBeDefined();
+  });
+
+  it('streams and flushes a manually started segment span', () => {
+    const client = initSdk();
+    const envelopes = recordEnvelopes(client);
+
+    startSpan({ name: 'manual segment' }, () => {});
+    // The integration flushes the trace 500ms after the segment span ends.
+    vi.advanceTimersByTime(500);
+
+    expect(envelopes).toHaveLength(1);
+    expect(envelopes[0]![0].trace).toBeDefined();
+    expect(getStreamedSpans(envelopes)).toEqual([
+      expect.objectContaining({ name: 'manual segment', is_segment: true }),
+    ]);
+  });
+
+  // `browserTracingIntegration` starts the pageload span through `startIdleSpan`, which is easy to
+  // overlook when wrapping the span-start APIs - and leaves auto-instrumented traces silently unsent.
+  it('installs the integration and streams the pageload segment with `browserTracingIntegration` alone', () => {
+    const client = initSdk({ integrations: [browserTracingIntegration()] });
+
+    expect(client?.getIntegrationByName('SpanStreaming')).toBeDefined();
+
+    const envelopes = recordEnvelopes(client);
+
+    // Let the idle span time out, then let the post-segment flush timer fire.
+    vi.advanceTimersByTime(60_000);
+    vi.advanceTimersByTime(500);
+
+    expect(getStreamedSpans(envelopes)).toContainEqual(expect.objectContaining({ name: '/', is_segment: true }));
+  });
+});
diff --git a/packages/effect/src/tracer.ts b/packages/effect/src/tracer.ts
index 7e23b9e5e014..8c91c3b67aae 100644
--- a/packages/effect/src/tracer.ts
+++ b/packages/effect/src/tracer.ts
@@ -5,13 +5,11 @@ import {
   WEB_SERVER_HTTP_SERVER_SPAN_OP,
 } from '@sentry/conventions/op';
 import type { Span } from '@sentry/core';
-import {
-  isObjectLike,
-  getActiveSpan,
-  SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
-  startInactiveSpan,
-  withActiveSpan,
-} from '@sentry/core';
+import { isObjectLike, getActiveSpan, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, withActiveSpan } from '@sentry/core';
+// This tracer is shared by the client and the server entry, so it needs the browser variant, which
+// installs the span streaming integration on first use. On the server that's a no-op: the client
+// already installs it eagerly, and `addIntegration` dedupes by name.
+import { startInactiveSpan } from '@sentry/core/browser';
 import type * as Context from 'effect/Context';
 import * as Exit from 'effect/Exit';
 import * as Option from 'effect/Option';
diff --git a/packages/effect/test/layer.test.ts b/packages/effect/test/layer.test.ts
index 3226f0c7faa2..0e928c25c0d7 100644
--- a/packages/effect/test/layer.test.ts
+++ b/packages/effect/test/layer.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from '@effect/vitest';
-import * as sentryCore from '@sentry/core';
+import * as sentryCoreBrowser from '@sentry/core/browser';
 import { getClient, getMainCarrier, SDK_VERSION } from '@sentry/core';
 import { Effect, Layer, Logger } from 'effect';
 import * as References from 'effect/References';
@@ -92,7 +92,7 @@ describe.each([
 
   it.effect('layer enables tracing when tracer is set', () =>
     Effect.gen(function* () {
-      const startInactiveSpanMock = vi.spyOn(sentryCore, 'startInactiveSpan');
+      const startInactiveSpanMock = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan');
 
       const result = yield* Effect.withSpan('test-span')(Effect.succeed('traced'));
       expect(result).toBe('traced');
@@ -110,7 +110,7 @@ describe.each([
 
   it.effect('layer can be composed with tracer', () =>
     Effect.gen(function* () {
-      const startInactiveSpanMock = vi.spyOn(sentryCore, 'startInactiveSpan');
+      const startInactiveSpanMock = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan');
 
       const result = yield* Effect.succeed(42).pipe(
         Effect.map(n => n * 2),
@@ -150,7 +150,7 @@ describe.each([
 
   it.effect('layer can be composed with all Effect features', () =>
     Effect.gen(function* () {
-      const startInactiveSpanMock = vi.spyOn(sentryCore, 'startInactiveSpan');
+      const startInactiveSpanMock = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan');
 
       yield* Effect.logInfo('starting computation');
       const result = yield* Effect.succeed(42).pipe(
diff --git a/packages/effect/test/tracer.test.ts b/packages/effect/test/tracer.test.ts
index f9b25e91b491..0dfd2edb9bbf 100644
--- a/packages/effect/test/tracer.test.ts
+++ b/packages/effect/test/tracer.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from '@effect/vitest';
 import * as sentryCore from '@sentry/core';
+import * as sentryCoreBrowser from '@sentry/core/browser';
 import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
 import { Effect } from 'effect';
 import { afterEach, vi } from 'vitest';
@@ -117,7 +118,7 @@ describe('SentryEffectTracer', () => {
     Effect.gen(function* () {
       const setStatusCalls: Array<{ code: number; message?: string }> = [];
 
-      const mockStartInactiveSpan = vi.spyOn(sentryCore, 'startInactiveSpan').mockImplementation(_options => {
+      const mockStartInactiveSpan = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan').mockImplementation(_options => {
         return {
           spanContext: () => ({ spanId: 'test-span-id', traceId: 'test-trace-id' }),
           isRecording: () => true,
@@ -140,7 +141,7 @@ describe('SentryEffectTracer', () => {
     Effect.gen(function* () {
       const setStatusCalls: Array<{ code: number; message?: string }> = [];
 
-      const mockStartInactiveSpan = vi.spyOn(sentryCore, 'startInactiveSpan').mockImplementation(_options => {
+      const mockStartInactiveSpan = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan').mockImplementation(_options => {
         return {
           spanContext: () => ({ spanId: 'test-span-id', traceId: 'test-trace-id' }),
           isRecording: () => true,
@@ -163,7 +164,7 @@ describe('SentryEffectTracer', () => {
     Effect.gen(function* () {
       const setStatusCalls: Array<{ code: number; message?: string }> = [];
 
-      const mockStartInactiveSpan = vi.spyOn(sentryCore, 'startInactiveSpan').mockImplementation(_options => {
+      const mockStartInactiveSpan = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan').mockImplementation(_options => {
         return {
           spanContext: () => ({ spanId: 'test-span-id', traceId: 'test-trace-id' }),
           isRecording: () => true,
@@ -207,7 +208,7 @@ describe('SentryEffectTracer', () => {
     Effect.gen(function* () {
       let capturedAttributes: Record<string, unknown> | undefined;
 
-      const mockStartInactiveSpan = vi.spyOn(sentryCore, 'startInactiveSpan').mockImplementation(options => {
+      const mockStartInactiveSpan = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan').mockImplementation(options => {
         capturedAttributes = options.attributes;
         return {
           spanContext: () => ({ spanId: 'test-span-id', traceId: 'test-trace-id' }),
@@ -233,7 +234,7 @@ describe('SentryEffectTracer', () => {
     Effect.gen(function* () {
       let capturedAttributes: Record<string, unknown> | undefined;
 
-      const mockStartInactiveSpan = vi.spyOn(sentryCore, 'startInactiveSpan').mockImplementation(options => {
+      const mockStartInactiveSpan = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan').mockImplementation(options => {
         capturedAttributes = options.attributes;
         return {
           spanContext: () => ({ spanId: 'test-span-id', traceId: 'test-trace-id' }),
@@ -259,7 +260,7 @@ describe('SentryEffectTracer', () => {
     Effect.gen(function* () {
       let capturedAttributes: Record<string, unknown> | undefined;
 
-      const mockStartInactiveSpan = vi.spyOn(sentryCore, 'startInactiveSpan').mockImplementation(options => {
+      const mockStartInactiveSpan = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan').mockImplementation(options => {
         capturedAttributes = options.attributes;
         return {
           spanContext: () => ({ spanId: 'test-span-id', traceId: 'test-trace-id' }),
diff --git a/packages/eslint-plugin-sdk/src/index.js b/packages/eslint-plugin-sdk/src/index.js
index ce0cd671c08d..949edb72dc55 100644
--- a/packages/eslint-plugin-sdk/src/index.js
+++ b/packages/eslint-plugin-sdk/src/index.js
@@ -17,5 +17,6 @@ module.exports = {
     'no-skipped-tests': require('./rules/no-skipped-tests'),
     'no-unsafe-random-apis': require('./rules/no-unsafe-random-apis'),
     'no-unfiltered-url-attributes': require('./rules/no-unfiltered-url-attributes'),
+    'no-unguarded-span-apis': require('./rules/no-unguarded-span-apis'),
   },
 };
diff --git a/packages/eslint-plugin-sdk/src/rules/no-unguarded-span-apis.js b/packages/eslint-plugin-sdk/src/rules/no-unguarded-span-apis.js
new file mode 100644
index 000000000000..b7727acdf148
--- /dev/null
+++ b/packages/eslint-plugin-sdk/src/rules/no-unguarded-span-apis.js
@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * @fileoverview Rule to keep browser-facing code on the `@sentry/core/browser` span-start APIs.
+ *
+ * `startSpan`, `startInactiveSpan`, `startSpanManual` and `startIdleSpan` exist in two variants
+ * under the same name: the plain ones at `@sentry/core` / `@sentry/core/server`, and guarded ones at
+ * `@sentry/core/browser` that install `spanStreamingIntegration` on the client before starting the
+ * span. The browser SDK's `init()` deliberately does not reference that integration - that reference
+ * alone would keep the whole span streaming graph in every bundle, including error-only ones.
+ *
+ * Because both variants share their names, importing the plain one in browser code compiles fine and
+ * creates spans that are then never sent. This rule is the only thing that catches it.
+ */
+
+const SPAN_START_APIS = ['startSpan', 'startInactiveSpan', 'startSpanManual', 'startIdleSpan'];
+
+const RESTRICTED_SOURCES = ['@sentry/core', '@sentry/core/server'];
+
+/**
+ * Which parts of which package are browser-facing.
+ *
+ * `true` means the package's whole `src` (plus `addon`, for ember) ships to the browser. An array
+ * lists the paths that do, for packages that also contain server, edge or build-time code - those
+ * must keep using the plain `@sentry/core` APIs.
+ */
+const BROWSER_FACING = {
+  angular: true,
+  browser: true,
+  'browser-utils': true,
+  ember: true,
+  feedback: true,
+  gatsby: true,
+  react: true,
+  'replay-canvas': true,
+  'replay-internal': true,
+  solid: true,
+  svelte: true,
+  vue: true,
+  wasm: true,
+
+  astro: ['src/client'],
+  // `tracer.ts` backs both the client and the server entry, so it needs the guarded variant too.
+  effect: ['src/client', 'src/tracer.ts'],
+  nextjs: ['src/client'],
+  nuxt: ['src/client'],
+  'react-router': ['src/client'],
+  remix: ['src/client'],
+  solidstart: ['src/client'],
+  sveltekit: ['src/client'],
+  'tanstackstart-react': ['src/client'],
+};
+
+/** Resolve `<package>` and the package-relative path out of a file path. */
+function splitPackagePath(filename) {
+  const match = /(?:^|\/)packages\/([^/]+)\/(.+)$/.exec(filename.replace(/\\/g, '/'));
+  return match ? { pkg: match[1], path: match[2] } : undefined;
+}
+
+function isBrowserFacing(filename) {
+  const location = splitPackagePath(filename);
+  if (!location) {
+    return false;
+  }
+
+  const scope = BROWSER_FACING[location.pkg];
+  if (!scope) {
+    return false;
+  }
+
+  if (scope === true) {
+    return location.path.startsWith('src/') || location.path.startsWith('addon/');
+  }
+
+  return scope.some(prefix => location.path === prefix || location.path.startsWith(`${prefix}/`));
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Enforce importing span-start APIs from `@sentry/core/browser` in browser-facing code',
+      category: 'Possible Errors',
+      recommended: true,
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      unguardedSpanApi:
+        '`{{name}}` must be imported from `@sentry/core/browser` (or `@sentry/browser`) in browser-facing code. The `{{source}}` variant does not install `spanStreamingIntegration`, so spans it starts are created but never sent.',
+    },
+  },
+  create: function (context) {
+    if (!isBrowserFacing(context.getFilename())) {
+      return {};
+    }
+
+    return {
+      ImportDeclaration(node) {
+        // `import type { startSpan }` is only ever used for signatures, never to start a span.
+        if (node.importKind === 'type' || !RESTRICTED_SOURCES.includes(node.source.value)) {
+          return;
+        }
+
+        for (const specifier of node.specifiers) {
+          if (
+            specifier.type === 'ImportSpecifier' &&
+            specifier.importKind !== 'type' &&
+            SPAN_START_APIS.includes(specifier.imported.name)
+          ) {
+            context.report({
+              node: specifier,
+              messageId: 'unguardedSpanApi',
+              data: { name: specifier.imported.name, source: node.source.value },
+            });
+          }
+        }
+      },
+    };
+  },
+};
diff --git a/packages/eslint-plugin-sdk/test/lib/rules/no-unguarded-span-apis.test.ts b/packages/eslint-plugin-sdk/test/lib/rules/no-unguarded-span-apis.test.ts
new file mode 100644
index 000000000000..ef174481d73a
--- /dev/null
+++ b/packages/eslint-plugin-sdk/test/lib/rules/no-unguarded-span-apis.test.ts
@@ -0,0 +1,131 @@
+import { RuleTester } from 'eslint';
+import { describe, expect, test } from 'vitest';
+// @ts-expect-error untyped module
+import rule from '../../../src/rules/no-unguarded-span-apis';
+
+const BROWSER_FILE = '/repo/packages/browser/src/tracing/request.ts';
+
+describe('no-unguarded-span-apis', () => {
+  test('ruleTester', () => {
+    const ruleTester = new RuleTester({
+      parserOptions: {
+        ecmaVersion: 2020,
+        sourceType: 'module',
+      },
+    });
+
+    ruleTester.run('no-unguarded-span-apis', rule, {
+      valid: [
+        // The guarded entry point is the whole point of the rule.
+        {
+          filename: BROWSER_FILE,
+          code: "import { startSpan } from '@sentry/core/browser';",
+        },
+        {
+          filename: BROWSER_FILE,
+          code: "import { startSpan } from '@sentry/browser';",
+        },
+        // Non-span imports from the root entry stay fine - browser code has plenty of those.
+        {
+          filename: BROWSER_FILE,
+          code: "import { debug, spanToJSON } from '@sentry/core';",
+        },
+        // Server, edge and build-time code must keep using the plain variants.
+        {
+          filename: '/repo/packages/node/src/sdk/index.ts',
+          code: "import { startSpan } from '@sentry/core';",
+        },
+        {
+          filename: '/repo/packages/nextjs/src/server/index.ts',
+          code: "import { startSpan } from '@sentry/core';",
+        },
+        {
+          filename: '/repo/packages/effect/src/server/index.ts',
+          code: "import { startSpan } from '@sentry/core';",
+        },
+        // Tests and build config in browser packages don't ship to the browser.
+        {
+          filename: '/repo/packages/browser/test/tracing/request.test.ts',
+          code: "import { startSpan } from '@sentry/core';",
+        },
+      ],
+      invalid: [
+        {
+          filename: BROWSER_FILE,
+          code: "import { startSpan } from '@sentry/core';",
+          errors: [{ messageId: 'unguardedSpanApi' }],
+        },
+        {
+          filename: BROWSER_FILE,
+          code: "import { debug, startInactiveSpan, startSpanManual } from '@sentry/core';",
+          errors: [{ messageId: 'unguardedSpanApi' }, { messageId: 'unguardedSpanApi' }],
+        },
+        {
+          filename: BROWSER_FILE,
+          code: "import { startIdleSpan } from '@sentry/core/server';",
+          errors: [{ messageId: 'unguardedSpanApi' }],
+        },
+        // Only `src/client` of a meta-framework package is browser-facing...
+        {
+          filename: '/repo/packages/nextjs/src/client/routing.ts',
+          code: "import { startSpan } from '@sentry/core';",
+          errors: [{ messageId: 'unguardedSpanApi' }],
+        },
+        // ...except for files explicitly listed as shared between both entry points.
+        {
+          filename: '/repo/packages/effect/src/tracer.ts',
+          code: "import { startInactiveSpan } from '@sentry/core';",
+          errors: [{ messageId: 'unguardedSpanApi' }],
+        },
+        // Ember ships from `addon`, not `src`.
+        {
+          filename: '/repo/packages/ember/addon/index.ts',
+          code: "import { startSpan } from '@sentry/core';",
+          errors: [{ messageId: 'unguardedSpanApi' }],
+        },
+      ],
+    });
+  });
+
+  // `import type { startSpan }` and `import { type startSpan }` only ever feed signatures, never
+  // start a span, so the rule must ignore them. RuleTester can't cover this: the repo has no working
+  // TypeScript parser for ESLint (`@typescript-eslint/parser@5` can't run against `typescript@7`),
+  // so we drive the visitor with the `ImportDeclaration` shape that parser would produce.
+  describe('type-only imports are ignored', () => {
+    function runOnImport(node: unknown): unknown[] {
+      const reports: unknown[] = [];
+      const visitor = rule.create({
+        getFilename: () => BROWSER_FILE,
+        report: (descriptor: unknown) => reports.push(descriptor),
+      });
+      visitor.ImportDeclaration?.(node);
+      return reports;
+    }
+
+    const specifier = (name: string, importKind: string | undefined) => ({
+      type: 'ImportSpecifier',
+      importKind,
+      imported: { name },
+    });
+
+    test('ignores `import type { startSpan }`', () => {
+      expect(
+        runOnImport({
+          importKind: 'type',
+          source: { value: '@sentry/core' },
+          specifiers: [specifier('startSpan', 'value')],
+        }),
+      ).toEqual([]);
+    });
+
+    test('ignores an inline `type` specifier but still reports its siblings', () => {
+      expect(
+        runOnImport({
+          importKind: 'value',
+          source: { value: '@sentry/core' },
+          specifiers: [specifier('startIdleSpan', 'type'), specifier('startSpan', 'value')],
+        }),
+      ).toEqual([expect.objectContaining({ data: { name: 'startSpan', source: '@sentry/core' } })]);
+    });
+  });
+});
diff --git a/packages/nextjs/src/client/index.ts b/packages/nextjs/src/client/index.ts
index 5c557c4cc66b..e80750d9e174 100644
--- a/packages/nextjs/src/client/index.ts
+++ b/packages/nextjs/src/client/index.ts
@@ -19,8 +19,10 @@ export * from '@sentry/react';
 export * from '../common';
 export { captureUnderscoreErrorException } from '../common/pages-router-instrumentation/_error';
 
-// Override core span methods with Next.js-specific implementations that support Cache Components
-export { startSpan, startSpanManual, startInactiveSpan } from '../common/utils/nextSpan';
+// The Cache Components overrides in `../common/utils/nextSpan` are deliberately not re-exported
+// here: both of their no-op conditions - `isBuild()` (reads the server-only `NEXT_PHASE` env var)
+// and `isUseCacheFunction()` (a React server reference check) - are unreachable in the browser. So
+// the client keeps `@sentry/react`'s span APIs, which additionally install span streaming on demand.
 export { browserTracingIntegration } from './browserTracingIntegration';
 export { captureRouterTransitionStart } from './routing/appRouterRoutingInstrumentation';
 
diff --git a/packages/nextjs/src/index.types.ts b/packages/nextjs/src/index.types.ts
index 42ef9d6a9502..766eb7837d6d 100644
--- a/packages/nextjs/src/index.types.ts
+++ b/packages/nextjs/src/index.types.ts
@@ -27,6 +27,12 @@ export declare const consoleIntegration: typeof serverSdk.consoleIntegration;
 // Node-only at runtime; the edge build exports an inert shim so named imports resolve in edge-compiled modules.
 export declare const pinoIntegration: typeof serverSdk.pinoIntegration;
 export declare const spanStreamingIntegration: typeof clientSdk.spanStreamingIntegration;
+// The client uses the `@sentry/core/browser` span-start APIs while server and edge use the Cache
+// Components-aware ones from `common/utils/nextSpan`. Same signatures, but the star exports above
+// are ambiguous without these.
+export declare const startSpan: typeof clientSdk.startSpan;
+export declare const startSpanManual: typeof clientSdk.startSpanManual;
+export declare const startInactiveSpan: typeof clientSdk.startInactiveSpan;
 export declare const withStaticSpan: typeof clientSdk.withStaticSpan;
 // oxlint-disable-next-line typescript/no-deprecated
 export declare const withStreamedSpan: typeof clientSdk.withStreamedSpan;
diff --git a/packages/react-router/src/client/createClientInstrumentation.ts b/packages/react-router/src/client/createClientInstrumentation.ts
index 24cc79b7095f..53a07a88f4ec 100644
--- a/packages/react-router/src/client/createClientInstrumentation.ts
+++ b/packages/react-router/src/client/createClientInstrumentation.ts
@@ -12,10 +12,10 @@ import {
   SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
   spanToJSON,
   SPAN_STATUS_ERROR,
-  startSpan,
   updateSpanName,
   filterCollectedUrl,
 } from '@sentry/core';
+import { startSpan } from '@sentry/core/browser';
 import { DEBUG_BUILD } from '../common/debug-build';
 import type { ClientInstrumentation, InstrumentableRoute, InstrumentableRouter } from '../common/types';
 import { captureInstrumentationError, getPathFromRequest, getPattern, normalizeRoutePath } from '../common/utils';
diff --git a/packages/react-router/test/client/createClientInstrumentation.test.ts b/packages/react-router/test/client/createClientInstrumentation.test.ts
index 676247b27948..8a5b697a7567 100644
--- a/packages/react-router/test/client/createClientInstrumentation.test.ts
+++ b/packages/react-router/test/client/createClientInstrumentation.test.ts
@@ -1,5 +1,6 @@
 import * as browser from '@sentry/browser';
 import * as core from '@sentry/core';
+import * as coreBrowser from '@sentry/core/browser';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import {
   createSentryClientInstrumentation,
@@ -7,11 +8,18 @@ import {
   isNavigateHookInvoked,
 } from '../../src/client/createClientInstrumentation';
 
+vi.mock('@sentry/core/browser', async () => {
+  const actual = await vi.importActual('@sentry/core/browser');
+  return {
+    ...actual,
+    startSpan: vi.fn(),
+  };
+});
+
 vi.mock('@sentry/core', async () => {
   const actual = await vi.importActual('@sentry/core');
   return {
     ...actual,
-    startSpan: vi.fn(),
     captureException: vi.fn(),
     getClient: vi.fn(),
     getActiveSpan: vi.fn(),
@@ -195,7 +203,7 @@ describe('createSentryClientInstrumentation', () => {
     const mockCallFetch = vi.fn().mockResolvedValue({ status: 'success', error: undefined });
     const mockInstrument = vi.fn();
 
-    (core.startSpan as any).mockImplementation((_opts: any, fn: any) => fn());
+    (coreBrowser.startSpan as any).mockImplementation((_opts: any, fn: any) => fn());
 
     const instrumentation = createSentryClientInstrumentation();
     instrumentation.router?.({ instrument: mockInstrument });
@@ -209,7 +217,7 @@ describe('createSentryClientInstrumentation', () => {
       fetcherKey: 'fetcher-1',
     });
 
-    expect(core.startSpan).toHaveBeenCalledWith(
+    expect(coreBrowser.startSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         name: 'Fetcher fetcher-1',
         attributes: expect.objectContaining({
@@ -227,7 +235,7 @@ describe('createSentryClientInstrumentation', () => {
     const mockCallLoader = vi.fn().mockResolvedValue({ status: 'success', error: undefined });
     const mockInstrument = vi.fn();
 
-    (core.startSpan as any).mockImplementation((_opts: any, fn: any) => fn());
+    (coreBrowser.startSpan as any).mockImplementation((_opts: any, fn: any) => fn());
 
     const instrumentation = createSentryClientInstrumentation();
     // Route has id, index, path as required properties
@@ -249,7 +257,7 @@ describe('createSentryClientInstrumentation', () => {
       context: undefined,
     });
 
-    expect(core.startSpan).toHaveBeenCalledWith(
+    expect(coreBrowser.startSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         name: '/users/:id',
         attributes: expect.objectContaining({
@@ -267,7 +275,7 @@ describe('createSentryClientInstrumentation', () => {
     const mockCallAction = vi.fn().mockResolvedValue({ status: 'success', error: undefined });
     const mockInstrument = vi.fn();
 
-    (core.startSpan as any).mockImplementation((_opts: any, fn: any) => fn());
+    (coreBrowser.startSpan as any).mockImplementation((_opts: any, fn: any) => fn());
 
     const instrumentation = createSentryClientInstrumentation();
     instrumentation.route?.({
@@ -287,7 +295,7 @@ describe('createSentryClientInstrumentation', () => {
       context: undefined,
     });
 
-    expect(core.startSpan).toHaveBeenCalledWith(
+    expect(coreBrowser.startSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         name: '/users/:id',
         attributes: expect.objectContaining({
@@ -335,7 +343,7 @@ describe('createSentryClientInstrumentation', () => {
     const mockInstrument = vi.fn();
     const mockSpan = { setStatus: vi.fn() };
 
-    (core.startSpan as any).mockImplementation((_opts: any, fn: any) => fn(mockSpan));
+    (coreBrowser.startSpan as any).mockImplementation((_opts: any, fn: any) => fn(mockSpan));
 
     const instrumentation = createSentryClientInstrumentation();
     instrumentation.route?.({
@@ -369,7 +377,7 @@ describe('createSentryClientInstrumentation', () => {
     const mockInstrument = vi.fn();
     const mockSpan = { setStatus: vi.fn() };
 
-    (core.startSpan as any).mockImplementation((_opts: any, fn: any) => fn(mockSpan));
+    (coreBrowser.startSpan as any).mockImplementation((_opts: any, fn: any) => fn(mockSpan));
 
     const instrumentation = createSentryClientInstrumentation({ captureErrors: false });
     instrumentation.route?.({
@@ -581,7 +589,7 @@ describe('createSentryClientInstrumentation', () => {
     const mockCallLoader = vi.fn().mockResolvedValue({ status: 'success', error: undefined });
     const mockInstrument = vi.fn();
 
-    (core.startSpan as any).mockImplementation((_opts: any, fn: any) => fn());
+    (coreBrowser.startSpan as any).mockImplementation((_opts: any, fn: any) => fn());
 
     const instrumentation = createSentryClientInstrumentation();
     instrumentation.route?.({
@@ -601,7 +609,7 @@ describe('createSentryClientInstrumentation', () => {
       context: undefined,
     });
 
-    expect(core.startSpan).toHaveBeenCalledWith(
+    expect(coreBrowser.startSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         name: '/users/123',
       }),
@@ -613,7 +621,7 @@ describe('createSentryClientInstrumentation', () => {
     const mockCallMiddleware = vi.fn().mockResolvedValue({ status: 'success', error: undefined });
     const mockInstrument = vi.fn();
 
-    (core.startSpan as any).mockImplementation((_opts: any, fn: any) => fn());
+    (coreBrowser.startSpan as any).mockImplementation((_opts: any, fn: any) => fn());
 
     const instrumentation = createSentryClientInstrumentation();
     instrumentation.route?.({
@@ -632,7 +640,7 @@ describe('createSentryClientInstrumentation', () => {
       context: undefined,
     });
 
-    expect(core.startSpan).toHaveBeenCalledWith(
+    expect(coreBrowser.startSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         name: 'middleware test-route',
         attributes: expect.objectContaining({
@@ -652,7 +660,7 @@ describe('createSentryClientInstrumentation', () => {
     const mockCallLazy = vi.fn().mockResolvedValue({ status: 'success', error: undefined });
     const mockInstrument = vi.fn();
 
-    (core.startSpan as any).mockImplementation((_opts: any, fn: any) => fn());
+    (coreBrowser.startSpan as any).mockImplementation((_opts: any, fn: any) => fn());
 
     const instrumentation = createSentryClientInstrumentation();
     instrumentation.route?.({
@@ -666,7 +674,7 @@ describe('createSentryClientInstrumentation', () => {
 
     await hooks.lazy(mockCallLazy, undefined);
 
-    expect(core.startSpan).toHaveBeenCalledWith(
+    expect(coreBrowser.startSpan).toHaveBeenCalledWith(
       expect.objectContaining({
         name: 'Lazy Route Load',
         attributes: expect.objectContaining({
@@ -894,7 +902,7 @@ describe('isNavigateHookInvoked', () => {
 describe('navigation root parameterization', () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    (core.startSpan as any).mockImplementation((_opts: any, fn: any) => fn({ setStatus: vi.fn() }));
+    (coreBrowser.startSpan as any).mockImplementation((_opts: any, fn: any) => fn({ setStatus: vi.fn() }));
   });
 
   it('renames the active navigation/pageload root span with the route pattern from the loader hook', async () => {
diff --git a/packages/svelte/src/performance.ts b/packages/svelte/src/performance.ts
index 89c448988d8c..db8ae5056bdf 100644
--- a/packages/svelte/src/performance.ts
+++ b/packages/svelte/src/performance.ts
@@ -1,6 +1,7 @@
 import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/browser';
 import type { Span } from '@sentry/core';
-import { debug, startInactiveSpan } from '@sentry/core';
+import { debug } from '@sentry/core';
+import { startInactiveSpan } from '@sentry/core/browser';
 import { SENTRY_OP } from '@sentry/conventions/attributes';
 import { afterUpdate, beforeUpdate, onMount } from 'svelte';
 import { DEBUG_BUILD } from './debug_build';
diff --git a/packages/sveltekit/src/client/load.ts b/packages/sveltekit/src/client/load.ts
index bc95867e718a..046ea5df319a 100644
--- a/packages/sveltekit/src/client/load.ts
+++ b/packages/sveltekit/src/client/load.ts
@@ -4,8 +4,8 @@ import {
   objectify,
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
-  startSpan,
 } from '@sentry/core';
+import { startSpan } from '@sentry/core/browser';
 import { CODE_FUNCTION_NAME, SENTRY_OP } from '@sentry/conventions/attributes';
 import { GENERAL_FUNCTION_SPAN_OP } from '@sentry/conventions/op';
 import { captureException } from '@sentry/svelte';
diff --git a/packages/sveltekit/test/client/load.test.ts b/packages/sveltekit/test/client/load.test.ts
index 4cd67149ca05..c023baa48254 100644
--- a/packages/sveltekit/test/client/load.test.ts
+++ b/packages/sveltekit/test/client/load.test.ts
@@ -13,8 +13,8 @@ const mockCaptureException = vi.spyOn(SentrySvelte, 'captureException').mockImpl
 
 const mockStartSpan = vi.fn();
 
-vi.mock('@sentry/core', async () => {
-  const original = (await vi.importActual('@sentry/core')) as any;
+vi.mock('@sentry/core/browser', async () => {
+  const original = (await vi.importActual('@sentry/core/browser')) as any;
   return {
     ...original,
     startSpan: (...args: unknown[]) => {

From 5195eb47a3d61dca44f78e787346be4d6701f01b Mon Sep 17 00:00:00 2001
From: Lukas Stracke <lukas.stracke@sentry.io>
Date: Wed, 12 Aug 2026 19:22:25 +0200
Subject: [PATCH 2/5] deslop

---
 .size-limit.js                                |  9 +---
 .../browser-utils/src/performance/utils.ts    |  3 +-
 .../browser-utils/src/web-vitals/spans.ts     |  4 +-
 .../integrations/fetchStreamPerformance.ts    |  4 +-
 packages/browser/src/sdk.ts                   |  4 --
 packages/browser/test/sdk.test.ts             | 17 -------
 ...ing.test.ts => spanStreamingSetup.test.ts} | 50 ++-----------------
 packages/nextjs/src/client/index.ts           |  4 --
 .../src/client/createClientInstrumentation.ts |  4 +-
 9 files changed, 14 insertions(+), 85 deletions(-)
 rename packages/browser/test/tracing/{spanStreamingWiring.test.ts => spanStreamingSetup.test.ts} (60%)

diff --git a/.size-limit.js b/.size-limit.js
index ad6e4daca85e..725beb2023f1 100644
--- a/.size-limit.js
+++ b/.size-limit.js
@@ -3,15 +3,12 @@ const nodePrefixedBuiltinModules = builtinModules.map(m => `node:${m}`);
 
 module.exports = [
   // Browser SDK (ESM)
-  // The three `init`-only entries below are kept deliberately tight (< 1 KB headroom): an `init`
-  // that references `spanStreamingIntegration` again - directly or through a transitive import -
-  // costs ~1.6 KB here and would otherwise land unnoticed.
   {
     name: '@sentry/browser',
     path: 'packages/browser/build/npm/esm/prod/index.js',
     import: createImport('init'),
     gzip: true,
-    limit: '29.5 KB',
+    limit: '30 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
@@ -39,8 +36,6 @@ module.exports = [
     },
   },
   {
-    // Now that `init` no longer pulls in span streaming, this entry is within ~0.1 KB of the entry
-    // above. It stays as the floor: if the two ever diverge again, tracing code leaked back in.
     name: '@sentry/browser - with treeshaking flags tracing without tracing',
     path: 'packages/browser/build/npm/esm/prod/index.js',
     import: createImport('init'),
@@ -235,7 +230,7 @@ module.exports = [
     name: 'CDN Bundle',
     path: createCDNPath('bundle.min.js'),
     gzip: true,
-    limit: '38 KB',
+    limit: '32 KB',
     disablePlugins: ['@size-limit/esbuild'],
   },
   {
diff --git a/packages/browser-utils/src/performance/utils.ts b/packages/browser-utils/src/performance/utils.ts
index a9a9759e7ed5..6ab5e011672c 100644
--- a/packages/browser-utils/src/performance/utils.ts
+++ b/packages/browser-utils/src/performance/utils.ts
@@ -1,6 +1,5 @@
 import type { SentrySpan, Span, SpanTimeInput, StartSpanOptions } from '@sentry/core';
-import { spanToStaticSpanJSON, withActiveSpan } from '@sentry/core';
-import { startInactiveSpan } from '@sentry/core/browser';
+import { spanToStaticSpanJSON, withActiveSpan, startInactiveSpan } from '@sentry/core/browser';
 import { WINDOW } from '../types';
 
 /**
diff --git a/packages/browser-utils/src/web-vitals/spans.ts b/packages/browser-utils/src/web-vitals/spans.ts
index b0a42383bb03..7d0c41ea7724 100644
--- a/packages/browser-utils/src/web-vitals/spans.ts
+++ b/packages/browser-utils/src/web-vitals/spans.ts
@@ -12,8 +12,8 @@ import {
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   spanToJSON,
   timestampInSeconds,
-} from '@sentry/core';
-import { startInactiveSpan } from '@sentry/core/browser';
+  startInactiveSpan,
+} from '@sentry/core/browser';
 import { DEBUG_BUILD } from '../debug-build';
 import { htmlTreeAsString } from '../htmlTreeAsString';
 import { WINDOW } from '../types';
diff --git a/packages/browser/src/integrations/fetchStreamPerformance.ts b/packages/browser/src/integrations/fetchStreamPerformance.ts
index 746e578fc9b6..d03e668f89a6 100644
--- a/packages/browser/src/integrations/fetchStreamPerformance.ts
+++ b/packages/browser/src/integrations/fetchStreamPerformance.ts
@@ -10,8 +10,8 @@ import {
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   stripDataUrlContent,
   filterCollectedUrl,
-} from '@sentry/core';
-import { startInactiveSpan } from '@sentry/core/browser';
+  startInactiveSpan,
+} from '@sentry/core/browser';
 
 const responseToStreamSpan = new WeakMap<object, Span>();
 const responseToFallbackTimeout = new WeakMap<object, ReturnType<typeof setTimeout>>();
diff --git a/packages/browser/src/sdk.ts b/packages/browser/src/sdk.ts
index c819c2e132ba..9384e53821c6 100644
--- a/packages/browser/src/sdk.ts
+++ b/packages/browser/src/sdk.ts
@@ -113,10 +113,6 @@ export function init(options: BrowserOptions = {}): Client | undefined {
     defaultIntegrations,
   });
 
-  // `spanStreamingIntegration` is deliberately not added here: referencing it from `init()` would
-  // pull the entire span streaming graph into every bundle, including error-only ones. Instead the
-  // span-start APIs in `@sentry/core/browser` install it on first use — see `browserSpanApi.ts`.
-
   const clientOptions: BrowserClientOptions = {
     ...options,
     enabled: shouldDisableBecauseIsBrowserExtenstion ? false : options.enabled,
diff --git a/packages/browser/test/sdk.test.ts b/packages/browser/test/sdk.test.ts
index f96a78311f1c..3d84da69e565 100644
--- a/packages/browser/test/sdk.test.ts
+++ b/packages/browser/test/sdk.test.ts
@@ -61,23 +61,6 @@ describe('init', () => {
     expect(optionsPassed?.integrations.length).toBeGreaterThan(0);
   });
 
-  // `init` must not reference `spanStreamingIntegration`: that reference alone is what keeps the
-  // whole span streaming graph in error-only bundles. It is installed lazily by the span-start APIs
-  // instead - see `_INTERNAL_ensureBrowserSpanStreaming`.
-  it.each([
-    ['default integrations', undefined],
-    ['default integrations disabled', false as const],
-  ])('does not install spanStreamingIntegration with %s', (_, defaultIntegrations) => {
-    // @ts-expect-error this is fine for testing
-    const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind').mockImplementationOnce(() => {});
-    const options = getDefaultBrowserOptions({ dsn: PUBLIC_DSN, defaultIntegrations });
-
-    init(options);
-
-    const optionsPassed = initAndBindSpy.mock.calls[0]?.[1];
-    expect(optionsPassed?.integrations.some(integration => integration.name === 'SpanStreaming')).toBe(false);
-  });
-
   test("doesn't install default integrations if told not to", () => {
     const DEFAULT_INTEGRATIONS: Integration[] = [
       new MockIntegration('MockIntegration 0.3'),
diff --git a/packages/browser/test/tracing/spanStreamingWiring.test.ts b/packages/browser/test/tracing/spanStreamingSetup.test.ts
similarity index 60%
rename from packages/browser/test/tracing/spanStreamingWiring.test.ts
rename to packages/browser/test/tracing/spanStreamingSetup.test.ts
index 9745a3a8b811..ad30caa397d9 100644
--- a/packages/browser/test/tracing/spanStreamingWiring.test.ts
+++ b/packages/browser/test/tracing/spanStreamingSetup.test.ts
@@ -1,14 +1,12 @@
-/**
- * @vitest-environment jsdom
- */
-
-import type { Client, Envelope } from '@sentry/core/browser';
+import type { Client } from '@sentry/core/browser';
 import {
   createTransport,
   getMainCarrier,
   resolvedSyncPromise,
+  startIdleSpan,
   startInactiveSpan,
   startSpan,
+  startSpanManual,
 } from '@sentry/core/browser';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { BrowserOptions } from '../../src';
@@ -27,23 +25,6 @@ function initSdk(options: Partial<BrowserOptions> = {}): Client | undefined {
   });
 }
 
-function recordEnvelopes(client: Client | undefined): Envelope[] {
-  const envelopes: Envelope[] = [];
-  vi.spyOn(client!, 'sendEnvelope').mockImplementation(envelope => {
-    envelopes.push(envelope);
-    return resolvedSyncPromise({});
-  });
-  return envelopes;
-}
-
-/** Pulls the serialized spans out of the span v2 container items of the recorded envelopes. */
-function getStreamedSpans(envelopes: Envelope[]): Array<{ name?: string; is_segment?: boolean }> {
-  return envelopes
-    .flatMap(([, items]) => items)
-    .filter(([itemHeader]) => itemHeader.type === 'span')
-    .flatMap(([, payload]) => (payload as { items: Array<{ name?: string; is_segment?: boolean }> }).items);
-}
-
 describe('span streaming wiring', () => {
   beforeEach(() => {
     getMainCarrier().__SENTRY__ = undefined;
@@ -72,6 +53,8 @@ describe('span streaming wiring', () => {
   it.each([
     ['startSpan', () => startSpan({ name: 'test' }, () => {})],
     ['startInactiveSpan', () => startInactiveSpan({ name: 'test' }).end()],
+    ['startIdleSpan', () => startIdleSpan({ name: 'test' })],
+    ['startSpanManual', () => startSpanManual({ name: 'test' }, () => {})],
   ])('installs the integration when the first span is started via %s', (_, startTestSpan) => {
     const client = initSdk();
     expect(client?.getIntegrationByName('SpanStreaming')).toBeUndefined();
@@ -81,34 +64,11 @@ describe('span streaming wiring', () => {
     expect(client?.getIntegrationByName('SpanStreaming')).toBeDefined();
   });
 
-  it('streams and flushes a manually started segment span', () => {
-    const client = initSdk();
-    const envelopes = recordEnvelopes(client);
-
-    startSpan({ name: 'manual segment' }, () => {});
-    // The integration flushes the trace 500ms after the segment span ends.
-    vi.advanceTimersByTime(500);
-
-    expect(envelopes).toHaveLength(1);
-    expect(envelopes[0]![0].trace).toBeDefined();
-    expect(getStreamedSpans(envelopes)).toEqual([
-      expect.objectContaining({ name: 'manual segment', is_segment: true }),
-    ]);
-  });
-
   // `browserTracingIntegration` starts the pageload span through `startIdleSpan`, which is easy to
   // overlook when wrapping the span-start APIs - and leaves auto-instrumented traces silently unsent.
   it('installs the integration and streams the pageload segment with `browserTracingIntegration` alone', () => {
     const client = initSdk({ integrations: [browserTracingIntegration()] });
 
     expect(client?.getIntegrationByName('SpanStreaming')).toBeDefined();
-
-    const envelopes = recordEnvelopes(client);
-
-    // Let the idle span time out, then let the post-segment flush timer fire.
-    vi.advanceTimersByTime(60_000);
-    vi.advanceTimersByTime(500);
-
-    expect(getStreamedSpans(envelopes)).toContainEqual(expect.objectContaining({ name: '/', is_segment: true }));
   });
 });
diff --git a/packages/nextjs/src/client/index.ts b/packages/nextjs/src/client/index.ts
index e80750d9e174..c5de307078c7 100644
--- a/packages/nextjs/src/client/index.ts
+++ b/packages/nextjs/src/client/index.ts
@@ -19,10 +19,6 @@ export * from '@sentry/react';
 export * from '../common';
 export { captureUnderscoreErrorException } from '../common/pages-router-instrumentation/_error';
 
-// The Cache Components overrides in `../common/utils/nextSpan` are deliberately not re-exported
-// here: both of their no-op conditions - `isBuild()` (reads the server-only `NEXT_PHASE` env var)
-// and `isUseCacheFunction()` (a React server reference check) - are unreachable in the browser. So
-// the client keeps `@sentry/react`'s span APIs, which additionally install span streaming on demand.
 export { browserTracingIntegration } from './browserTracingIntegration';
 export { captureRouterTransitionStart } from './routing/appRouterRoutingInstrumentation';
 
diff --git a/packages/react-router/src/client/createClientInstrumentation.ts b/packages/react-router/src/client/createClientInstrumentation.ts
index 53a07a88f4ec..0ba1412ab287 100644
--- a/packages/react-router/src/client/createClientInstrumentation.ts
+++ b/packages/react-router/src/client/createClientInstrumentation.ts
@@ -12,10 +12,10 @@ import {
   SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
   spanToJSON,
   SPAN_STATUS_ERROR,
+  startSpan,
   updateSpanName,
   filterCollectedUrl,
-} from '@sentry/core';
-import { startSpan } from '@sentry/core/browser';
+} from '@sentry/core/browser';
 import { DEBUG_BUILD } from '../common/debug-build';
 import type { ClientInstrumentation, InstrumentableRoute, InstrumentableRouter } from '../common/types';
 import { captureInstrumentationError, getPathFromRequest, getPattern, normalizeRoutePath } from '../common/utils';

From d3f92f1a163d4a152520922cd99e53b02834c3f9 Mon Sep 17 00:00:00 2001
From: Lukas Stracke <lukas.stracke@sentry.io>
Date: Thu, 13 Aug 2026 12:29:55 +0200
Subject: [PATCH 3/5] add server and client tracer in effect

---
 packages/effect/src/client/tracer.ts          |  11 +
 packages/effect/src/index.client.ts           |   2 +-
 packages/effect/src/index.server.ts           |   2 +-
 packages/effect/src/index.types.ts            |   1 +
 packages/effect/src/server/tracer.ts          |  13 +
 packages/effect/src/tracer.ts                 |  31 ++-
 packages/effect/test/layer.test.ts            | 248 +++++++++---------
 packages/effect/test/tracer.test.ts           | 211 ++++++---------
 .../src/rules/no-unguarded-span-apis.js       |   3 +-
 .../lib/rules/no-unguarded-span-apis.test.ts  |   9 +-
 10 files changed, 257 insertions(+), 274 deletions(-)
 create mode 100644 packages/effect/src/client/tracer.ts
 create mode 100644 packages/effect/src/server/tracer.ts

diff --git a/packages/effect/src/client/tracer.ts b/packages/effect/src/client/tracer.ts
new file mode 100644
index 000000000000..e824286ddf60
--- /dev/null
+++ b/packages/effect/src/client/tracer.ts
@@ -0,0 +1,11 @@
+import { startInactiveSpan } from '@sentry/core/browser';
+import { makeSentryTracer } from '../tracer';
+
+/**
+ * Effect `Tracer` that records Effect spans as Sentry spans in browser clients.
+ *
+ * Wrapped in an arrow rather than passed by reference so the import binding is read per span. That
+ * keeps the browser variant substitutable (mocks, bundler interop) exactly as it was when the tracer
+ * called it directly.
+ */
+export const SentryEffectTracer = makeSentryTracer(options => startInactiveSpan(options));
diff --git a/packages/effect/src/index.client.ts b/packages/effect/src/index.client.ts
index 2df8a2548fb9..76aba91e5d04 100644
--- a/packages/effect/src/index.client.ts
+++ b/packages/effect/src/index.client.ts
@@ -6,6 +6,6 @@ export * from '@sentry/browser';
 export { effectLayer, init } from './client/index';
 export type { EffectClientLayerOptions } from './client/index';
 
-export { SentryEffectTracer } from './tracer';
+export { SentryEffectTracer } from './client/tracer';
 export { SentryEffectLogger } from './logger';
 export { SentryEffectMetricsLayer } from './metrics';
diff --git a/packages/effect/src/index.server.ts b/packages/effect/src/index.server.ts
index 95cc939dd497..01d9272ce6a9 100644
--- a/packages/effect/src/index.server.ts
+++ b/packages/effect/src/index.server.ts
@@ -3,6 +3,6 @@ export * from '@sentry/node';
 export { effectLayer, init } from './server/index';
 export type { EffectServerLayerOptions } from './server/index';
 
-export { SentryEffectTracer } from './tracer';
+export { SentryEffectTracer } from './server/tracer';
 export { SentryEffectLogger } from './logger';
 export { SentryEffectMetricsLayer } from './metrics';
diff --git a/packages/effect/src/index.types.ts b/packages/effect/src/index.types.ts
index 5311b8a6f24e..aef1f1ac98c6 100644
--- a/packages/effect/src/index.types.ts
+++ b/packages/effect/src/index.types.ts
@@ -22,6 +22,7 @@ export declare function init(options: Options | clientSdk.BrowserOptions | serve
 export declare const linkedErrorsIntegration: typeof clientSdk.linkedErrorsIntegration;
 export declare const contextLinesIntegration: typeof clientSdk.contextLinesIntegration;
 export declare const spanStreamingIntegration: typeof clientSdk.spanStreamingIntegration;
+export declare const SentryEffectTracer: typeof clientSdk.SentryEffectTracer;
 export declare const startSpan: typeof clientSdk.startSpan;
 export declare const startSpanManual: typeof clientSdk.startSpanManual;
 export declare const startInactiveSpan: typeof clientSdk.startInactiveSpan;
diff --git a/packages/effect/src/server/tracer.ts b/packages/effect/src/server/tracer.ts
new file mode 100644
index 000000000000..d4b622c2ba5c
--- /dev/null
+++ b/packages/effect/src/server/tracer.ts
@@ -0,0 +1,13 @@
+import { startInactiveSpan } from '@sentry/core';
+import { makeSentryTracer } from '../tracer';
+
+/**
+ * Effect `Tracer` that records Effect spans as Sentry spans on the server.
+ *
+ * Deliberately the plain `@sentry/core` variant, not `@sentry/core/browser`: the browser one guards
+ * every span start with a `getClient()` lookup to lazily install `spanStreamingIntegration`, which on
+ * the server is pure overhead — `ServerRuntimeClient` already installs it eagerly.
+ *
+ * See `./client/tracer.ts` for why the call is wrapped in an arrow.
+ */
+export const SentryEffectTracer = makeSentryTracer(options => startInactiveSpan(options));
diff --git a/packages/effect/src/tracer.ts b/packages/effect/src/tracer.ts
index 8c91c3b67aae..328f36bdce98 100644
--- a/packages/effect/src/tracer.ts
+++ b/packages/effect/src/tracer.ts
@@ -4,12 +4,8 @@ import {
   WEB_SERVER_HTTP_CLIENT_SPAN_OP,
   WEB_SERVER_HTTP_SERVER_SPAN_OP,
 } from '@sentry/conventions/op';
-import type { Span } from '@sentry/core';
+import type { Span, StartSpanOptions } from '@sentry/core';
 import { isObjectLike, getActiveSpan, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, withActiveSpan } from '@sentry/core';
-// This tracer is shared by the client and the server entry, so it needs the browser variant, which
-// installs the span streaming integration on first use. On the server that's a no-op: the client
-// already installs it eagerly, and `addIntegration` dedupes by name.
-import { startInactiveSpan } from '@sentry/core/browser';
 import type * as Context from 'effect/Context';
 import * as Exit from 'effect/Exit';
 import * as Option from 'effect/Option';
@@ -178,7 +174,16 @@ class SentrySpanWrapper implements SentrySpanLike {
   }
 }
 
+/**
+ * The client and the server entry differ only in which `startInactiveSpan` they hand to
+ * {@link makeSentryTracer}: the browser one from `@sentry/core/browser`, which installs the span
+ * streaming integration on first use, and the plain one from `@sentry/core`, which does not. Nothing
+ * else about the tracer is platform-specific.
+ */
+export type StartInactiveSpan = (options: StartSpanOptions) => Span;
+
 function createSentrySpan(
+  startInactiveSpan: StartInactiveSpan,
   name: string,
   parent: Option.Option<EffectTracer.AnySpan>,
   context: Context.Context<never>,
@@ -219,7 +224,7 @@ const isEffectV4 = (() => {
   }
 })();
 
-const makeSentryTracerV3 = (): EffectTracer.Tracer => {
+const makeSentryTracerV3 = (startInactiveSpan: StartInactiveSpan): EffectTracer.Tracer => {
   // Effect v3 API: span(name, parent, context, links, startTime, kind)
   return EffectTracer.make({
     span(
@@ -230,7 +235,7 @@ const makeSentryTracerV3 = (): EffectTracer.Tracer => {
       startTime: bigint,
       kind: EffectTracer.SpanKind,
     ) {
-      return createSentrySpan(name, parent, context, links, startTime, kind);
+      return createSentrySpan(startInactiveSpan, name, parent, context, links, startTime, kind);
     },
     context(execution: () => unknown, fiber: { currentSpan?: EffectTracer.AnySpan }) {
       const currentSpan = fiber.currentSpan;
@@ -242,12 +247,13 @@ const makeSentryTracerV3 = (): EffectTracer.Tracer => {
   } as unknown as EffectTracer.Tracer);
 };
 
-const makeSentryTracerV4 = (): EffectTracer.Tracer => {
+const makeSentryTracerV4 = (startInactiveSpan: StartInactiveSpan): EffectTracer.Tracer => {
   const EFFECT_EVALUATE = '~effect/Effect/evaluate' as const;
 
   return EffectTracer.make({
     span(options) {
       return createSentrySpan(
+        startInactiveSpan,
         options.name,
         options.parent,
         options.annotations,
@@ -267,6 +273,11 @@ const makeSentryTracerV4 = (): EffectTracer.Tracer => {
 };
 
 /**
- * Effect Layer that sets up the Sentry tracer for Effect spans.
+ * Creates an Effect `Tracer` that records Effect spans as Sentry spans.
+ *
+ * Use the `SentryEffectTracer` exported from `@sentry/effect` rather than calling this directly — the
+ * client and server entries each bind the right `startInactiveSpan` for their platform.
  */
-export const SentryEffectTracer = isEffectV4 ? makeSentryTracerV4() : makeSentryTracerV3();
+export function makeSentryTracer(startInactiveSpan: StartInactiveSpan): EffectTracer.Tracer {
+  return isEffectV4 ? makeSentryTracerV4(startInactiveSpan) : makeSentryTracerV3(startInactiveSpan);
+}
diff --git a/packages/effect/test/layer.test.ts b/packages/effect/test/layer.test.ts
index 0e928c25c0d7..31493c589d88 100644
--- a/packages/effect/test/layer.test.ts
+++ b/packages/effect/test/layer.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from '@effect/vitest';
+import * as sentryCore from '@sentry/core';
 import * as sentryCoreBrowser from '@sentry/core/browser';
 import { getClient, getMainCarrier, SDK_VERSION } from '@sentry/core';
 import { Effect, Layer, Logger } from 'effect';
@@ -24,6 +25,7 @@ describe.each([
       SentryEffectTracer: sentryClient.SentryEffectTracer,
       SentryEffectLogger: sentryClient.SentryEffectLogger,
       SentryEffectMetricsLayer: sentryClient.SentryEffectMetricsLayer,
+      startInactiveSpan: sentryCoreBrowser as { startInactiveSpan: typeof sentryCore.startInactiveSpan },
     },
   ],
   [
@@ -33,145 +35,149 @@ describe.each([
       SentryEffectTracer: sentryServer.SentryEffectTracer,
       SentryEffectLogger: sentryServer.SentryEffectLogger,
       SentryEffectMetricsLayer: sentryServer.SentryEffectMetricsLayer,
+      startInactiveSpan: sentryCore as { startInactiveSpan: typeof sentryCore.startInactiveSpan },
     },
   ],
-])('effectLayer ($subSdkName)', ({ subSdkName, effectLayer, SentryEffectTracer, SentryEffectLogger }) => {
-  beforeEach(() => {
-    getMainCarrier().__SENTRY__ = undefined;
-  });
+])(
+  'effectLayer ($subSdkName)',
+  ({ subSdkName, effectLayer, SentryEffectTracer, SentryEffectLogger, startInactiveSpan }) => {
+    beforeEach(() => {
+      getMainCarrier().__SENTRY__ = undefined;
+    });
 
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('creates a valid Effect layer', () => {
+      const layer = effectLayer({
+        dsn: TEST_DSN,
+        transport: getMockTransport(),
+      });
 
-  it('creates a valid Effect layer', () => {
-    const layer = effectLayer({
-      dsn: TEST_DSN,
-      transport: getMockTransport(),
+      expect(layer).toBeDefined();
+      expect(Layer.isLayer(layer)).toBe(true);
     });
 
-    expect(layer).toBeDefined();
-    expect(Layer.isLayer(layer)).toBe(true);
-  });
+    it.effect('applies SDK metadata', () =>
+      Effect.gen(function* () {
+        yield* Effect.void;
 
-  it.effect('applies SDK metadata', () =>
-    Effect.gen(function* () {
-      yield* Effect.void;
-
-      const client = getClient();
-      const metadata = client?.getOptions()._metadata?.sdk;
-
-      expect(metadata?.name).toBe('sentry.javascript.effect');
-      expect(metadata?.packages).toEqual([
-        { name: 'npm:@sentry/effect', version: SDK_VERSION },
-        { name: `npm:@sentry/${subSdkName}`, version: SDK_VERSION },
-      ]);
-    }).pipe(
-      Effect.provide(
-        effectLayer({
-          dsn: TEST_DSN,
-          transport: getMockTransport(),
-        }),
-      ),
-    ),
-  );
-
-  it.effect('layer can be provided to an Effect program', () =>
-    Effect.gen(function* () {
-      const result = yield* Effect.succeed('test-result');
-      expect(result).toBe('test-result');
-    }).pipe(
-      Effect.provide(
-        effectLayer({
-          dsn: TEST_DSN,
-          transport: getMockTransport(),
-        }),
-      ),
-    ),
-  );
-
-  it.effect('layer enables tracing when tracer is set', () =>
-    Effect.gen(function* () {
-      const startInactiveSpanMock = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan');
-
-      const result = yield* Effect.withSpan('test-span')(Effect.succeed('traced'));
-      expect(result).toBe('traced');
-      expect(startInactiveSpanMock).toHaveBeenCalledWith(expect.objectContaining({ name: 'test-span' }));
-    }).pipe(
-      Effect.withTracer(SentryEffectTracer),
-      Effect.provide(
-        effectLayer({
-          dsn: TEST_DSN,
-          transport: getMockTransport(),
-        }),
+        const client = getClient();
+        const metadata = client?.getOptions()._metadata?.sdk;
+
+        expect(metadata?.name).toBe('sentry.javascript.effect');
+        expect(metadata?.packages).toEqual([
+          { name: 'npm:@sentry/effect', version: SDK_VERSION },
+          { name: `npm:@sentry/${subSdkName}`, version: SDK_VERSION },
+        ]);
+      }).pipe(
+        Effect.provide(
+          effectLayer({
+            dsn: TEST_DSN,
+            transport: getMockTransport(),
+          }),
+        ),
       ),
-    ),
-  );
-
-  it.effect('layer can be composed with tracer', () =>
-    Effect.gen(function* () {
-      const startInactiveSpanMock = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan');
-
-      const result = yield* Effect.succeed(42).pipe(
-        Effect.map(n => n * 2),
-        Effect.withSpan('computation'),
-      );
-      expect(result).toBe(84);
-      expect(startInactiveSpanMock).toHaveBeenCalledWith(expect.objectContaining({ name: 'computation' }));
-    }).pipe(
-      Effect.withTracer(SentryEffectTracer),
-      Effect.provide(
-        effectLayer({
-          dsn: TEST_DSN,
-          transport: getMockTransport(),
-        }),
+    );
+
+    it.effect('layer can be provided to an Effect program', () =>
+      Effect.gen(function* () {
+        const result = yield* Effect.succeed('test-result');
+        expect(result).toBe('test-result');
+      }).pipe(
+        Effect.provide(
+          effectLayer({
+            dsn: TEST_DSN,
+            transport: getMockTransport(),
+          }),
+        ),
       ),
-    ),
-  );
-
-  it.effect('layer can be composed with logger', () =>
-    Effect.gen(function* () {
-      yield* Effect.logInfo('test log');
-      const result = yield* Effect.succeed('logged');
-      expect(result).toBe('logged');
-    }).pipe(
-      Effect.provideService(References.MinimumLogLevel, 'All'),
-      Effect.provide(
-        Layer.mergeAll(
+    );
+
+    it.effect('layer enables tracing when tracer is set', () =>
+      Effect.gen(function* () {
+        const startInactiveSpanMock = vi.spyOn(startInactiveSpan, 'startInactiveSpan');
+
+        const result = yield* Effect.withSpan('test-span')(Effect.succeed('traced'));
+        expect(result).toBe('traced');
+        expect(startInactiveSpanMock).toHaveBeenCalledWith(expect.objectContaining({ name: 'test-span' }));
+      }).pipe(
+        Effect.withTracer(SentryEffectTracer),
+        Effect.provide(
           effectLayer({
             dsn: TEST_DSN,
             transport: getMockTransport(),
           }),
-          Logger.layer([SentryEffectLogger]),
         ),
       ),
-    ),
-  );
-
-  it.effect('layer can be composed with all Effect features', () =>
-    Effect.gen(function* () {
-      const startInactiveSpanMock = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan');
-
-      yield* Effect.logInfo('starting computation');
-      const result = yield* Effect.succeed(42).pipe(
-        Effect.map(n => n * 2),
-        Effect.withSpan('computation'),
-      );
-      yield* Effect.logInfo('computation complete');
-      expect(result).toBe(84);
-      expect(startInactiveSpanMock).toHaveBeenCalledWith(expect.objectContaining({ name: 'computation' }));
-    }).pipe(
-      Effect.withTracer(SentryEffectTracer),
-      Effect.provideService(References.MinimumLogLevel, 'All'),
-      Effect.provide(
-        Layer.mergeAll(
+    );
+
+    it.effect('layer can be composed with tracer', () =>
+      Effect.gen(function* () {
+        const startInactiveSpanMock = vi.spyOn(startInactiveSpan, 'startInactiveSpan');
+
+        const result = yield* Effect.succeed(42).pipe(
+          Effect.map(n => n * 2),
+          Effect.withSpan('computation'),
+        );
+        expect(result).toBe(84);
+        expect(startInactiveSpanMock).toHaveBeenCalledWith(expect.objectContaining({ name: 'computation' }));
+      }).pipe(
+        Effect.withTracer(SentryEffectTracer),
+        Effect.provide(
           effectLayer({
             dsn: TEST_DSN,
             transport: getMockTransport(),
           }),
-          Logger.layer([SentryEffectLogger]),
         ),
       ),
-    ),
-  );
-});
+    );
+
+    it.effect('layer can be composed with logger', () =>
+      Effect.gen(function* () {
+        yield* Effect.logInfo('test log');
+        const result = yield* Effect.succeed('logged');
+        expect(result).toBe('logged');
+      }).pipe(
+        Effect.provideService(References.MinimumLogLevel, 'All'),
+        Effect.provide(
+          Layer.mergeAll(
+            effectLayer({
+              dsn: TEST_DSN,
+              transport: getMockTransport(),
+            }),
+            Logger.layer([SentryEffectLogger]),
+          ),
+        ),
+      ),
+    );
+
+    it.effect('layer can be composed with all Effect features', () =>
+      Effect.gen(function* () {
+        const startInactiveSpanMock = vi.spyOn(startInactiveSpan, 'startInactiveSpan');
+
+        yield* Effect.logInfo('starting computation');
+        const result = yield* Effect.succeed(42).pipe(
+          Effect.map(n => n * 2),
+          Effect.withSpan('computation'),
+        );
+        yield* Effect.logInfo('computation complete');
+        expect(result).toBe(84);
+        expect(startInactiveSpanMock).toHaveBeenCalledWith(expect.objectContaining({ name: 'computation' }));
+      }).pipe(
+        Effect.withTracer(SentryEffectTracer),
+        Effect.provideService(References.MinimumLogLevel, 'All'),
+        Effect.provide(
+          Layer.mergeAll(
+            effectLayer({
+              dsn: TEST_DSN,
+              transport: getMockTransport(),
+            }),
+            Logger.layer([SentryEffectLogger]),
+          ),
+        ),
+      ),
+    );
+  },
+);
diff --git a/packages/effect/test/tracer.test.ts b/packages/effect/test/tracer.test.ts
index 0dfd2edb9bbf..a056227576e1 100644
--- a/packages/effect/test/tracer.test.ts
+++ b/packages/effect/test/tracer.test.ts
@@ -4,11 +4,36 @@ import * as sentryCoreBrowser from '@sentry/core/browser';
 import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
 import { Effect } from 'effect';
 import { afterEach, vi } from 'vitest';
-import { SentryEffectTracer } from '../src/tracer';
+import { SentryEffectTracer as clientTracer } from '../src/client/tracer';
+import { SentryEffectTracer as serverTracer } from '../src/server/tracer';
+
+// The two variants differ only in which module they start spans through, so spying on `spanApi` also
+// asserts that wiring: the client tracer must go through `@sentry/core/browser` (which installs
+// `spanStreamingIntegration`) and the server tracer through the plain `@sentry/core`.
+const VARIANTS = [
+  { variant: 'client', tracer: clientTracer, spanApi: sentryCoreBrowser as SpanApi },
+  { variant: 'server', tracer: serverTracer, spanApi: sentryCore as SpanApi },
+];
+
+interface SpanApi {
+  startInactiveSpan: typeof sentryCore.startInactiveSpan;
+}
+
+function mockSpan(overrides: Record<string, unknown> = {}): sentryCore.Span {
+  return {
+    spanContext: () => ({ spanId: 'test-span-id', traceId: 'test-trace-id' }),
+    isRecording: () => true,
+    setAttribute: vi.fn(),
+    setStatus: vi.fn(),
+    addEvent: vi.fn(),
+    end: vi.fn(),
+    ...overrides,
+  } as unknown as sentryCore.Span;
+}
+
+describe.each(VARIANTS)('SentryEffectTracer ($variant)', ({ tracer, spanApi }) => {
+  const withSentryTracer = <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.withTracer(effect, tracer);
 
-const withSentryTracer = <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.withTracer(effect, SentryEffectTracer);
-
-describe('SentryEffectTracer', () => {
   afterEach(() => {
     vi.restoreAllMocks();
   });
@@ -58,45 +83,22 @@ describe('SentryEffectTracer', () => {
           results.push('parent-start');
           yield* Effect.withSpan('child-1')(Effect.sync(() => results.push('child-1')));
           yield* Effect.withSpan('child-2')(Effect.sync(() => results.push('child-2')));
-          results.push('parent-end');
         }),
       );
 
-      expect(results).toEqual(['parent-start', 'child-1', 'child-2', 'parent-end']);
-    }).pipe(withSentryTracer),
-  );
-
-  it.effect('handles span failures correctly', () =>
-    Effect.gen(function* () {
-      const result = yield* Effect.withSpan('failing-span')(Effect.fail('expected-error')).pipe(
-        Effect.catchCause(cause => {
-          const error = cause.reasons[0]?._tag === 'Fail' ? cause.reasons[0].error : 'unknown';
-          return Effect.succeed(`caught: ${error}`);
-        }),
-      );
-
-      expect(result).toBe('caught: expected-error');
-    }).pipe(withSentryTracer),
-  );
-
-  it.effect('handles span with defects (die)', () =>
-    Effect.gen(function* () {
-      const result = yield* Effect.withSpan('defect-span')(Effect.die('defect-value')).pipe(
-        Effect.catchDefect(d => Effect.succeed(`caught-defect: ${d}`)),
-      );
-
-      expect(result).toBe('caught-defect: defect-value');
+      expect(results).toEqual(['parent-start', 'child-1', 'child-2']);
     }).pipe(withSentryTracer),
   );
 
-  it.effect('works with Effect.all for parallel operations', () =>
+  it.effect('handles concurrent spans', () =>
     Effect.gen(function* () {
-      const results = yield* Effect.withSpan('parallel-parent')(
-        Effect.all([
-          Effect.withSpan('task-1')(Effect.succeed(1)),
-          Effect.withSpan('task-2')(Effect.succeed(2)),
-          Effect.withSpan('task-3')(Effect.succeed(3)),
-        ]),
+      const results = yield* Effect.all(
+        [
+          Effect.withSpan('concurrent-1')(Effect.succeed(1)),
+          Effect.withSpan('concurrent-2')(Effect.succeed(2)),
+          Effect.withSpan('concurrent-3')(Effect.succeed(3)),
+        ],
+        { concurrency: 'unbounded' },
       );
 
       expect(results).toEqual([1, 2, 3]);
@@ -118,22 +120,13 @@ describe('SentryEffectTracer', () => {
     Effect.gen(function* () {
       const setStatusCalls: Array<{ code: number; message?: string }> = [];
 
-      const mockStartInactiveSpan = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan').mockImplementation(_options => {
-        return {
-          spanContext: () => ({ spanId: 'test-span-id', traceId: 'test-trace-id' }),
-          isRecording: () => true,
-          setAttribute: vi.fn(),
-          setStatus: (status: { code: number; message?: string }) => setStatusCalls.push(status),
-          addEvent: vi.fn(),
-          end: vi.fn(),
-        } as unknown as sentryCore.Span;
-      });
+      vi.spyOn(spanApi, 'startInactiveSpan').mockImplementation(() =>
+        mockSpan({ setStatus: (status: { code: number; message?: string }) => setStatusCalls.push(status) }),
+      );
 
       yield* Effect.withSpan('success-span')(Effect.succeed('ok'));
 
       expect(setStatusCalls).toContainEqual({ code: 1 });
-
-      mockStartInactiveSpan.mockRestore();
     }).pipe(withSentryTracer),
   );
 
@@ -141,22 +134,13 @@ describe('SentryEffectTracer', () => {
     Effect.gen(function* () {
       const setStatusCalls: Array<{ code: number; message?: string }> = [];
 
-      const mockStartInactiveSpan = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan').mockImplementation(_options => {
-        return {
-          spanContext: () => ({ spanId: 'test-span-id', traceId: 'test-trace-id' }),
-          isRecording: () => true,
-          setAttribute: vi.fn(),
-          setStatus: (status: { code: number; message?: string }) => setStatusCalls.push(status),
-          addEvent: vi.fn(),
-          end: vi.fn(),
-        } as unknown as sentryCore.Span;
-      });
+      vi.spyOn(spanApi, 'startInactiveSpan').mockImplementation(() =>
+        mockSpan({ setStatus: (status: { code: number; message?: string }) => setStatusCalls.push(status) }),
+      );
 
       yield* Effect.withSpan('error-span')(Effect.fail('test-error')).pipe(Effect.catchCause(() => Effect.void));
 
       expect(setStatusCalls).toContainEqual({ code: 2, message: 'test-error' });
-
-      mockStartInactiveSpan.mockRestore();
     }).pipe(withSentryTracer),
   );
 
@@ -164,22 +148,13 @@ describe('SentryEffectTracer', () => {
     Effect.gen(function* () {
       const setStatusCalls: Array<{ code: number; message?: string }> = [];
 
-      const mockStartInactiveSpan = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan').mockImplementation(_options => {
-        return {
-          spanContext: () => ({ spanId: 'test-span-id', traceId: 'test-trace-id' }),
-          isRecording: () => true,
-          setAttribute: vi.fn(),
-          setStatus: (status: { code: number; message?: string }) => setStatusCalls.push(status),
-          addEvent: vi.fn(),
-          end: vi.fn(),
-        } as unknown as sentryCore.Span;
-      });
+      vi.spyOn(spanApi, 'startInactiveSpan').mockImplementation(() =>
+        mockSpan({ setStatus: (status: { code: number; message?: string }) => setStatusCalls.push(status) }),
+      );
 
       yield* Effect.withSpan('defect-span')(Effect.die('fatal-defect')).pipe(Effect.catchDefect(() => Effect.void));
 
       expect(setStatusCalls).toContainEqual({ code: 2, message: 'fatal-defect' });
-
-      mockStartInactiveSpan.mockRestore();
     }).pipe(withSentryTracer),
   );
 
@@ -187,105 +162,67 @@ describe('SentryEffectTracer', () => {
     Effect.gen(function* () {
       const withActiveSpanCalls: sentryCore.Span[] = [];
 
-      const mockWithActiveSpan = vi
-        .spyOn(sentryCore, 'withActiveSpan')
-        .mockImplementation(<T>(span: sentryCore.Span | null, callback: (scope: sentryCore.Scope) => T): T => {
+      vi.spyOn(sentryCore, 'withActiveSpan').mockImplementation(
+        <T>(span: sentryCore.Span | null, callback: (scope: sentryCore.Scope) => T): T => {
           if (span) {
             withActiveSpanCalls.push(span);
           }
           return callback({} as sentryCore.Scope);
-        });
+        },
+      );
 
       yield* Effect.withSpan('context-span')(Effect.succeed('done'));
 
       expect(withActiveSpanCalls.length).toBeGreaterThan(0);
-
-      mockWithActiveSpan.mockRestore();
     }).pipe(withSentryTracer),
   );
 
-  it.effect('sets origin and op for regular spans', () =>
+  /** Captures the attributes the tracer passes to `startInactiveSpan` for a given Effect span name. */
+  const attributesFor = (spanName: string) =>
     Effect.gen(function* () {
       let capturedAttributes: Record<string, unknown> | undefined;
 
-      const mockStartInactiveSpan = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan').mockImplementation(options => {
+      vi.spyOn(spanApi, 'startInactiveSpan').mockImplementation(options => {
         capturedAttributes = options.attributes;
-        return {
-          spanContext: () => ({ spanId: 'test-span-id', traceId: 'test-trace-id' }),
-          isRecording: () => true,
-          setAttribute: vi.fn(),
-          setStatus: vi.fn(),
-          addEvent: vi.fn(),
-          end: vi.fn(),
-        } as unknown as sentryCore.Span;
+        return mockSpan();
       });
 
-      yield* Effect.withSpan('my-operation')(Effect.succeed('ok'));
+      yield* Effect.withSpan(spanName)(Effect.succeed('ok'));
 
-      expect(capturedAttributes).toBeDefined();
-      expect(capturedAttributes?.[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]).toBe('auto.function.effect');
-      expect(capturedAttributes?.[SEMANTIC_ATTRIBUTE_SENTRY_OP]).toBe('function');
+      return capturedAttributes;
+    }).pipe(withSentryTracer);
 
-      mockStartInactiveSpan.mockRestore();
-    }).pipe(withSentryTracer),
+  it.effect('sets origin and op for regular spans', () =>
+    Effect.gen(function* () {
+      const attributes = yield* attributesFor('my-operation');
+
+      expect(attributes?.[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]).toBe('auto.function.effect');
+      expect(attributes?.[SEMANTIC_ATTRIBUTE_SENTRY_OP]).toBe('function');
+    }),
   );
 
   it.effect('sets origin and op for http.server spans', () =>
     Effect.gen(function* () {
-      let capturedAttributes: Record<string, unknown> | undefined;
-
-      const mockStartInactiveSpan = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan').mockImplementation(options => {
-        capturedAttributes = options.attributes;
-        return {
-          spanContext: () => ({ spanId: 'test-span-id', traceId: 'test-trace-id' }),
-          isRecording: () => true,
-          setAttribute: vi.fn(),
-          setStatus: vi.fn(),
-          addEvent: vi.fn(),
-          end: vi.fn(),
-        } as unknown as sentryCore.Span;
-      });
-
-      yield* Effect.withSpan('http.server GET /api/users')(Effect.succeed('ok'));
-
-      expect(capturedAttributes).toBeDefined();
-      expect(capturedAttributes?.[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]).toBe('auto.http.effect');
-      expect(capturedAttributes?.[SEMANTIC_ATTRIBUTE_SENTRY_OP]).toBe('http.server');
+      const attributes = yield* attributesFor('http.server GET /api/users');
 
-      mockStartInactiveSpan.mockRestore();
-    }).pipe(withSentryTracer),
+      expect(attributes?.[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]).toBe('auto.http.effect');
+      expect(attributes?.[SEMANTIC_ATTRIBUTE_SENTRY_OP]).toBe('http.server');
+    }),
   );
 
   it.effect('sets origin and op for http.client spans', () =>
     Effect.gen(function* () {
-      let capturedAttributes: Record<string, unknown> | undefined;
+      const attributes = yield* attributesFor('http.client GET https://api.example.com');
 
-      const mockStartInactiveSpan = vi.spyOn(sentryCoreBrowser, 'startInactiveSpan').mockImplementation(options => {
-        capturedAttributes = options.attributes;
-        return {
-          spanContext: () => ({ spanId: 'test-span-id', traceId: 'test-trace-id' }),
-          isRecording: () => true,
-          setAttribute: vi.fn(),
-          setStatus: vi.fn(),
-          addEvent: vi.fn(),
-          end: vi.fn(),
-        } as unknown as sentryCore.Span;
-      });
-
-      yield* Effect.withSpan('http.client GET https://api.example.com')(Effect.succeed('ok'));
-
-      expect(capturedAttributes).toBeDefined();
-      expect(capturedAttributes?.[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]).toBe('auto.http.effect');
-      expect(capturedAttributes?.[SEMANTIC_ATTRIBUTE_SENTRY_OP]).toBe('http.client');
-
-      mockStartInactiveSpan.mockRestore();
-    }).pipe(withSentryTracer),
+      expect(attributes?.[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]).toBe('auto.http.effect');
+      expect(attributes?.[SEMANTIC_ATTRIBUTE_SENTRY_OP]).toBe('http.client');
+    }),
   );
 
   it.effect('can be used with Effect.withTracer', () =>
     Effect.gen(function* () {
       const result = yield* Effect.withSpan('inline-tracer-span')(Effect.succeed('with-tracer'));
       expect(result).toBe('with-tracer');
-    }).pipe(Effect.withTracer(SentryEffectTracer)),
+    }).pipe(Effect.withTracer(tracer)),
   );
 });
diff --git a/packages/eslint-plugin-sdk/src/rules/no-unguarded-span-apis.js b/packages/eslint-plugin-sdk/src/rules/no-unguarded-span-apis.js
index b7727acdf148..76af668b9538 100644
--- a/packages/eslint-plugin-sdk/src/rules/no-unguarded-span-apis.js
+++ b/packages/eslint-plugin-sdk/src/rules/no-unguarded-span-apis.js
@@ -40,8 +40,7 @@ const BROWSER_FACING = {
   wasm: true,
 
   astro: ['src/client'],
-  // `tracer.ts` backs both the client and the server entry, so it needs the guarded variant too.
-  effect: ['src/client', 'src/tracer.ts'],
+  effect: ['src/client'],
   nextjs: ['src/client'],
   nuxt: ['src/client'],
   'react-router': ['src/client'],
diff --git a/packages/eslint-plugin-sdk/test/lib/rules/no-unguarded-span-apis.test.ts b/packages/eslint-plugin-sdk/test/lib/rules/no-unguarded-span-apis.test.ts
index ef174481d73a..4d73d53b46bf 100644
--- a/packages/eslint-plugin-sdk/test/lib/rules/no-unguarded-span-apis.test.ts
+++ b/packages/eslint-plugin-sdk/test/lib/rules/no-unguarded-span-apis.test.ts
@@ -43,6 +43,12 @@ describe('no-unguarded-span-apis', () => {
           filename: '/repo/packages/effect/src/server/index.ts',
           code: "import { startSpan } from '@sentry/core';",
         },
+        // `effect`'s shared tracer implementation takes `startInactiveSpan` as an argument, so it is
+        // not itself browser-facing - only `src/client/tracer.ts` binds the guarded variant.
+        {
+          filename: '/repo/packages/effect/src/tracer.ts',
+          code: "import { startInactiveSpan } from '@sentry/core';",
+        },
         // Tests and build config in browser packages don't ship to the browser.
         {
           filename: '/repo/packages/browser/test/tracing/request.test.ts',
@@ -71,9 +77,8 @@ describe('no-unguarded-span-apis', () => {
           code: "import { startSpan } from '@sentry/core';",
           errors: [{ messageId: 'unguardedSpanApi' }],
         },
-        // ...except for files explicitly listed as shared between both entry points.
         {
-          filename: '/repo/packages/effect/src/tracer.ts',
+          filename: '/repo/packages/effect/src/client/tracer.ts',
           code: "import { startInactiveSpan } from '@sentry/core';",
           errors: [{ messageId: 'unguardedSpanApi' }],
         },

From 99e50de0d3e45943b92d574372b68ca78e5ef830 Mon Sep 17 00:00:00 2001
From: Lukas Stracke <lukas.stracke@sentry.io>
Date: Thu, 13 Aug 2026 13:45:59 +0200
Subject: [PATCH 4/5] fix tests

---
 packages/browser-utils/src/web-vitals/spans.ts                | 4 ++--
 .../react-router/src/client/createClientInstrumentation.ts    | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/browser-utils/src/web-vitals/spans.ts b/packages/browser-utils/src/web-vitals/spans.ts
index 7d0c41ea7724..b0a42383bb03 100644
--- a/packages/browser-utils/src/web-vitals/spans.ts
+++ b/packages/browser-utils/src/web-vitals/spans.ts
@@ -12,8 +12,8 @@ import {
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   spanToJSON,
   timestampInSeconds,
-  startInactiveSpan,
-} from '@sentry/core/browser';
+} from '@sentry/core';
+import { startInactiveSpan } from '@sentry/core/browser';
 import { DEBUG_BUILD } from '../debug-build';
 import { htmlTreeAsString } from '../htmlTreeAsString';
 import { WINDOW } from '../types';
diff --git a/packages/react-router/src/client/createClientInstrumentation.ts b/packages/react-router/src/client/createClientInstrumentation.ts
index 0ba1412ab287..53a07a88f4ec 100644
--- a/packages/react-router/src/client/createClientInstrumentation.ts
+++ b/packages/react-router/src/client/createClientInstrumentation.ts
@@ -12,10 +12,10 @@ import {
   SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
   spanToJSON,
   SPAN_STATUS_ERROR,
-  startSpan,
   updateSpanName,
   filterCollectedUrl,
-} from '@sentry/core/browser';
+} from '@sentry/core';
+import { startSpan } from '@sentry/core/browser';
 import { DEBUG_BUILD } from '../common/debug-build';
 import type { ClientInstrumentation, InstrumentableRoute, InstrumentableRouter } from '../common/types';
 import { captureInstrumentationError, getPathFromRequest, getPattern, normalizeRoutePath } from '../common/utils';

From dacddff21944836f2b75a01a6d0864dd3b52e03d Mon Sep 17 00:00:00 2001
From: Lukas Stracke <lukas.stracke@sentry.io>
Date: Thu, 13 Aug 2026 18:54:28 +0200
Subject: [PATCH 5/5] fix build error

---
 packages/core/src/browser.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/core/src/browser.ts b/packages/core/src/browser.ts
index a0ba2b75ef01..22f34ce95a81 100644
--- a/packages/core/src/browser.ts
+++ b/packages/core/src/browser.ts
@@ -2,3 +2,5 @@
 
 export * from './shared-exports';
 export * from './browser-exports';
+
+export { startIdleSpan, startSpan, startInactiveSpan, startSpanManual } from './browser-exports';