feat: SpeedCurve LUX

[zizzfizzix]

Summary

• Adds useScriptSpeedCurve composable with full LUX SDK integration — automatic page-view tracking, SPA navigation support, and manual mode
• Registers SpeedCurve in the script registry with a 13-field Valibot schema covering LUX configuration options (samplerate, sendBeaconOnPageHidden, trackErrors, maxErrors, minMeasureTime, maxMeasureTime, newBeaconOnPageShow, trackHiddenPages, cookieDomain, and SPA-specific spaMode, autoTrackSpaNavigations, label)
• Adds comprehensive test coverage: 26 unit tests and 11 Playwright e2e tests with CDN blocking, covering primer injection, config application, auto-tracker, afterNextPaint, and SPA navigation scenarios (default label, custom label, label disabled, back navigation, cancelled navigation, manual mode)
• Includes logo (light/dark SVG), playground pages for each SPA mode (/third-parties/speed-curve/spa-auto, no-spa, manual-spa), and user-facing documentation in docs/scripts/speedcurve.md

Key design decisions

• afterNextPaint(fn) utility schedules markLoadTime after the next requestAnimationFrame flush so it runs after LUX's paint capture window closes
• SPA mode: when autoTrackSpaNavigations is enabled, vue-router beforeEach calls lux.startSoftNavigation() + sets the label; the page:finish Nuxt hook calls afterNextPaint(() => lux.markLoadTime()) to seal the beacon after render; afterEach seals cancelled-navigation phantom beacons with markLoadTime + addData('luxNavFailed', '1')
• label accepts string | ((to: RouteLocationNormalized) => string) | false — functions are resolved per navigation in beforeEach; false skips setting the label entirely; default falls back to String(to.name ?? to.path)
• HMR guard (luxWired module-level flag) prevents double-wiring the router hook during Vite hot reloads

Test plan

• pnpm test — all unit tests pass (speedcurve primer, config, auto-tracker, afterNextPaint)
• pnpm test:e2e — all e2e tests pass (CDN-blocked LUX, all SPA scenario variants)
• Playground at /third-parties/speed-curve/ — verify spa-auto, no-spa, and manual-spa A→B→C chains in browser
• Check SpeedCurve LUX dashboard after enabling with a real LUX_SITE_ID to confirm beacons fire correctly

[vercel]

@zizzfizzix is attempting to deploy a commit to the Nuxt Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds complete SpeedCurve LUX real-user monitoring (RUM) integration to Nuxt Scripts. The implementation includes a valibot schema defining configuration options (id, SPA mode, auto-tracking, label customization), a composable that injects the Lux primer, applies configuration, and automatically instruments Vue Router for soft navigation tracking on SPA navigations. The runtime includes an installAutoTracker function that wires router.beforeEach to start soft navigation and manage labels, router.afterEach to mark load time and tag failed navigations, and a page:finish hook for marking completion. Supporting infrastructure includes package dependency updates, type registry extensions, logo assets, and comprehensive unit and E2E test coverage demonstrating SPA auto-tracking, manual mode, no-SPA mode, and custom labeling scenarios.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 18.18% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, covering the composable, registry entry, test coverage, design decisions, and test plan—all aspects of the SpeedCurve integration being added.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title 'feat: SpeedCurve LUX' clearly summarizes the main change - adding SpeedCurve LUX integration to the codebase. It is concise, specific, and directly related to the extensive changeset that implements this feature.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

test/e2e/basic.test.ts (1)

15-19: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Separate setup from Playwright page options.

setup is test-helper metadata for configuring the page after creation, not a Playwright newPage option. Passing it directly to browser.newPage(options) would forward an unknown property to Playwright's API. Extract it before passing to newPage.

Proposed fix

 async function createPage(path: string, options?: any) {
   const logs: { text: string, location: string }[] = []
   const browser = await getBrowser()
-  const page = await browser.newPage(options)
+  const { setup: setupPage, ...pageOptions } = options ?? {}
+  const page = await browser.newPage(pageOptions)

-  if (options?.setup)
-    await options.setup(page)
+  if (setupPage)
+    await setupPage(page)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/e2e/basic.test.ts` around lines 15 - 19, The createPage helper is
passing test-helper metadata named "setup" into Playwright via
browser.newPage(options); extract and remove the setup property before calling
browser.newPage so only valid Playwright options are forwarded. In the
createPage function (reference symbols: createPage, getBrowser, browser.newPage,
setup) read/setup = options?.setup (or destructure { setup, ...playwrightOptions
} = options), call browser.newPage with playwrightOptions, then apply the setup
callback to the created page afterwards (e.g., await setup(page)) and keep the
logging and event wiring as-is.

🧹 Nitpick comments (4)

playground/pages/third-parties/speed-curve/spa-auto/a.vue (1)

2-2: 💤 Low value

Consider consistent import style.

Line 2 uses explicit imports for Nuxt composables, but lines 13–14 rely on auto-imports for Vue's ref and onMounted. While Nuxt auto-imports both by default, mixing explicit and auto-imports reduces consistency.

♻️ Option: Add explicit imports for consistency

-import { useHead, useScriptSpeedCurve } from '`#imports`'
+import { onMounted, ref, useHead, useScriptSpeedCurve } from '`#imports`'

Also applies to: 13-16

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@playground/pages/third-parties/speed-curve/spa-auto/a.vue` at line 2, The
file mixes explicit imports (useHead, useScriptSpeedCurve) with relying on Nuxt
auto-imports for Vue refs/onMounted (ref, onMounted), so make imports
consistent: add explicit imports for ref and onMounted alongside useHead and
useScriptSpeedCurve (or conversely remove explicit Nuxt composable imports and
rely on auto-imports for all), updating the import statement that currently
references useHead and useScriptSpeedCurve to also import ref and onMounted to
keep styling uniform and avoid ambiguity.

playground/pages/third-parties/speed-curve/spa-auto/b.vue (1)

2-2: 💤 Low value

Consider consistent import style.

Line 2 uses explicit imports for Nuxt composables, but lines 13–14 rely on auto-imports for Vue's ref and onMounted. While Nuxt auto-imports both by default, mixing explicit and auto-imports reduces consistency.

♻️ Option: Add explicit imports for consistency

-import { useHead, useScriptSpeedCurve } from '`#imports`'
+import { onMounted, ref, useHead, useScriptSpeedCurve } from '`#imports`'

Also applies to: 13-16

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@playground/pages/third-parties/speed-curve/spa-auto/b.vue` at line 2, The
file mixes explicit Nuxt imports (useHead, useScriptSpeedCurve) with
auto-imported Vue APIs (ref, onMounted); make the import style consistent by
adding explicit imports for Vue's ref and onMounted into the top import
statement (update the line importing useHead and useScriptSpeedCurve to also
import ref and onMounted) so references to ref and onMounted in this component
use the same explicit import pattern as useHead/useScriptSpeedCurve.

test/unit/speedcurve-auto-tracker.test.ts (1)

157-168: ⚡ Quick win

Add a regression test for label callback returning false.

Current tests validate function labels that return strings, but not the skip-update branch (false), which is a key route-labeling edge case.

Suggested test case

+  it('does not update label when label function returns false', async () => {
+    const lux = { startSoftNavigation: vi.fn(), markLoadTime: vi.fn(), addData: vi.fn(), label: 'keep-me' }
+    Object.defineProperty(window, 'LUX', { value: lux, writable: true, configurable: true })
+
+    const { installAutoTracker } = await import('../../packages/script/src/runtime/registry/speedcurve')
+    installAutoTracker({ id: '123', label: () => false })
+
+    const handler = mockBeforeEach.mock.calls[0][0] as (to: any) => void
+    handler({ name: 'about', path: '/about' })
+
+    expect(lux.label).toBe('keep-me')
+  })

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/unit/speedcurve-auto-tracker.test.ts` around lines 157 - 168, Add a
regression test to cover the branch where the provided label callback returns
false so route labels are skipped: in the existing test that imports
installAutoTracker from '../../packages/script/src/runtime/registry/speedcurve',
create a mock LUX (window.LUX) as in the current test, call installAutoTracker({
id: '123', label: () => false }), invoke the captured navigation handler from
mockBeforeEach (mockBeforeEach.mock.calls[0][0]) with a route object (e.g., {
name: 'about', path: '/about' }), and assert that lux.label was not updated
(remains initial empty string or unchanged) to verify the skip-update branch is
exercised.

test/e2e/speedcurve.test.ts (1)

8-14: ⚡ Quick win

Consider aligning async setup with Vitest best practices.

While Vitest supports async describe callbacks, the recommended approach is to use beforeAll hooks or test fixtures for asynchronous setup. This keeps test registration clean and defers setup execution to the test execution phase.

+import { beforeAll } from 'vitest'
+
 describe('speedcurve', { timeout: 15000 }, () => {
+  beforeAll(async () => {
+    await setup({
+      rootDir: resolve('../fixtures/speedcurve'),
+      browser: true,
+    })
+  })
   defineSpeedCurveSuite()
 })

Note: This pattern is used elsewhere in the codebase (e.g., _linkedin-insight-suite.ts), though several E2E tests currently use async describe. Consider whether a broader refactoring of E2E test setup is needed for consistency.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/e2e/speedcurve.test.ts` around lines 8 - 14, The describe callback
should not be async; move the await setup into a beforeAll hook so setup runs
during test execution rather than during registration: change
describe('speedcurve', { timeout: 15000 }, async () => { ... }) to a non-async
describe and add beforeAll(async () => { await setup({ rootDir:
resolve('../fixtures/speedcurve'), browser: true }) }) and then call
defineSpeedCurveSuite() (or call it after the beforeAll if it must run
post-setup), keeping the same timeout option; use the existing setup(),
resolve(), and defineSpeedCurveSuite() symbols to locate and update the code.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/content/scripts/speedcurve.md`:
- Around line 86-90: The fenced code block containing the CSP directives (the
triple-backtick block with lines "script-src  cdn.speedcurve.com;", "img-src    
lux.speedcurve.com;", "connect-src lux.speedcurve.com beacon.speedcurve.com;")
needs a language specified to satisfy MD040; update the opening backticks from
``` to ```text (or another appropriate language) so the block becomes a fenced
code block with a language tag.

In `@packages/script/src/registry-types.json`:
- Around line 969-980: The registry-types.json SpeedCurve contract is stale: the
exported SpeedCurveOptions const currently lists auto and a simple string label,
but the runtime schema's SpeedCurveOptions allows label to be string | function
| false and does not include auto; regenerate or update registry-types.json from
the runtime schema source so the exported SpeedCurveOptions and SpeedCurveApi
match exactly the runtime schema (ensure SpeedCurveOptions' properties, types
and defaults mirror the schema, and remove or add fields as needed, then re-run
whatever generator produces registry-types.json).

In `@packages/script/src/runtime/registry/schemas.ts`:
- Line 1: The samplerate field's schema currently allows any number even though
docs require 0–100; update the schema definition for the "samplerate" property
(the object schema around lines 1036-1039) to constrain values to the 0–100
range—e.g. use valibot's range validators (import and apply min and max) or wrap
number() with pipe/custom to enforce >=0 and <=100; ensure you also update the
import list (add min and max or the custom helper) so the schema validation
rejects out-of-range samplerate values.

In `@packages/script/src/runtime/registry/speedcurve.ts`:
- Around line 24-26: The dynamic label callback type in SpeedCurveInput is
currently declared to return only string but the API allows returning false;
update the label type to include false (i.e. label?: string | ((to:
RouteLocationNormalized) => string | false) | false) and in the runtime where
the callback is invoked (the code that assigns the callback result to lux.label
in the block around the current assignment at/near lux.label) guard the
assignment so you only set lux.label when the callback result !== false (leave
lux.label unchanged when the callback returns false). Ensure you reference
SpeedCurveInput and the runtime assignment to lux.label so both the type and the
runtime behavior are consistent.

---

Outside diff comments:
In `@test/e2e/basic.test.ts`:
- Around line 15-19: The createPage helper is passing test-helper metadata named
"setup" into Playwright via browser.newPage(options); extract and remove the
setup property before calling browser.newPage so only valid Playwright options
are forwarded. In the createPage function (reference symbols: createPage,
getBrowser, browser.newPage, setup) read/setup = options?.setup (or destructure
{ setup, ...playwrightOptions } = options), call browser.newPage with
playwrightOptions, then apply the setup callback to the created page afterwards
(e.g., await setup(page)) and keep the logging and event wiring as-is.

---

Nitpick comments:
In `@playground/pages/third-parties/speed-curve/spa-auto/a.vue`:
- Line 2: The file mixes explicit imports (useHead, useScriptSpeedCurve) with
relying on Nuxt auto-imports for Vue refs/onMounted (ref, onMounted), so make
imports consistent: add explicit imports for ref and onMounted alongside useHead
and useScriptSpeedCurve (or conversely remove explicit Nuxt composable imports
and rely on auto-imports for all), updating the import statement that currently
references useHead and useScriptSpeedCurve to also import ref and onMounted to
keep styling uniform and avoid ambiguity.

In `@playground/pages/third-parties/speed-curve/spa-auto/b.vue`:
- Line 2: The file mixes explicit Nuxt imports (useHead, useScriptSpeedCurve)
with auto-imported Vue APIs (ref, onMounted); make the import style consistent
by adding explicit imports for Vue's ref and onMounted into the top import
statement (update the line importing useHead and useScriptSpeedCurve to also
import ref and onMounted) so references to ref and onMounted in this component
use the same explicit import pattern as useHead/useScriptSpeedCurve.

In `@test/e2e/speedcurve.test.ts`:
- Around line 8-14: The describe callback should not be async; move the await
setup into a beforeAll hook so setup runs during test execution rather than
during registration: change describe('speedcurve', { timeout: 15000 }, async ()
=> { ... }) to a non-async describe and add beforeAll(async () => { await
setup({ rootDir: resolve('../fixtures/speedcurve'), browser: true }) }) and then
call defineSpeedCurveSuite() (or call it after the beforeAll if it must run
post-setup), keeping the same timeout option; use the existing setup(),
resolve(), and defineSpeedCurveSuite() symbols to locate and update the code.

In `@test/unit/speedcurve-auto-tracker.test.ts`:
- Around line 157-168: Add a regression test to cover the branch where the
provided label callback returns false so route labels are skipped: in the
existing test that imports installAutoTracker from
'../../packages/script/src/runtime/registry/speedcurve', create a mock LUX
(window.LUX) as in the current test, call installAutoTracker({ id: '123', label:
() => false }), invoke the captured navigation handler from mockBeforeEach
(mockBeforeEach.mock.calls[0][0]) with a route object (e.g., { name: 'about',
path: '/about' }), and assert that lux.label was not updated (remains initial
empty string or unchanged) to verify the skip-update branch is exercised.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0a445647-7d04-4794-a71e-6d675713a253

📥 Commits

Reviewing files that changed from the base of the PR and between 9e57294 and 8bd9201.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (44)

• FIRST_PARTY.md
• docs/content/scripts/speedcurve.md
• package.json
• packages/script/package.json
• packages/script/src/registry-logos.ts
• packages/script/src/registry-types.json
• packages/script/src/registry.ts
• packages/script/src/runtime/registry/schemas.ts
• packages/script/src/runtime/registry/speedcurve.ts
• packages/script/src/runtime/types.ts
• packages/script/src/runtime/utils/after-next-paint.ts
• packages/script/src/script-meta.ts
• playground/pages/third-parties/speed-curve/manual-spa/a.vue
• playground/pages/third-parties/speed-curve/manual-spa/b.vue
• playground/pages/third-parties/speed-curve/manual-spa/c.vue
• playground/pages/third-parties/speed-curve/no-spa/a.vue
• playground/pages/third-parties/speed-curve/no-spa/b.vue
• playground/pages/third-parties/speed-curve/no-spa/c.vue
• playground/pages/third-parties/speed-curve/spa-auto/a.vue
• playground/pages/third-parties/speed-curve/spa-auto/b.vue
• playground/pages/third-parties/speed-curve/spa-auto/c.vue
• pnpm-workspace.yaml
• scripts/generate-registry-types.ts
• test/e2e/_speedcurve-suite.ts
• test/e2e/basic.test.ts
• test/e2e/speedcurve.test.ts
• test/fixtures/speedcurve/app.vue
• test/fixtures/speedcurve/nuxt.config.ts
• test/fixtures/speedcurve/package.json
• test/fixtures/speedcurve/pages/tpc/speedcurve-custom-label/destination.vue
• test/fixtures/speedcurve/pages/tpc/speedcurve-custom-label/index.vue
• test/fixtures/speedcurve/pages/tpc/speedcurve-label-off/destination.vue
• test/fixtures/speedcurve/pages/tpc/speedcurve-label-off/index.vue
• test/fixtures/speedcurve/pages/tpc/speedcurve-manual/destination.vue
• test/fixtures/speedcurve/pages/tpc/speedcurve-manual/index.vue
• test/fixtures/speedcurve/pages/tpc/speedcurve-no-spa/destination.vue
• test/fixtures/speedcurve/pages/tpc/speedcurve-no-spa/index.vue
• test/fixtures/speedcurve/pages/tpc/speedcurve/destination.vue
• test/fixtures/speedcurve/pages/tpc/speedcurve/index.vue
• test/fixtures/speedcurve/tsconfig.json
• test/unit/speedcurve-after-next-paint.test.ts
• test/unit/speedcurve-auto-tracker.test.ts
• test/unit/speedcurve-config.test.ts
• test/unit/speedcurve-primer.test.ts

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@nuxt/scripts@782

commit: d0ff15a