diff --git a/docs/tracking-handoff-2026-09-28.md b/docs/tracking-handoff-2026-09-28.md new file mode 100644 index 000000000..b70d7695d --- /dev/null +++ b/docs/tracking-handoff-2026-09-28.md @@ -0,0 +1,97 @@ +# Tracking handoff audit, September 28, 2026 + +## Step 1: GA4 page views + +The reported navigation regression did not reproduce on the live site. Chrome DevTools showed one `page_view` in `dataLayer` and a corresponding GA collection request returning HTTP 204 for each of these visits, including navigation without a full reload: + +- `/` +- `/blog` +- `/query/latest` +- `/query/latest/docs/framework/react/overview` +- `/query/latest/docs/framework/react/installation` +- `/query/latest/docs/framework/react/quick-start` + +No GA4 application change is warranted by these results. HTTP 204 confirms that the collection endpoint accepted the request, not that GA4 processed it into a report. GA4 DebugView and the post-deploy BigQuery ratio have not been verified. + +Commit `b7c3ba5223ca6987d7b78ca2b6160c596688bfc6`, committed September 24 at 19:40:55 UTC, changed page-view counting intentionally: + +- It added an idempotent bootstrap guard to prevent repeated GA configuration and script loading. +- It set `send_page_view: false`, replacing automatic initial views with the existing React page-view tracker. +- It changed that tracker from skipping its first effect to sending an initial view and suppressing consecutive identical paths. +- It documented that GA4 Enhanced Measurement browser-history page changes must be disabled when manual navigation tracking is enabled. + +Before that change, config-generated initial views and manual navigation views could overlap with duplicate bootstrap execution or GA4 browser-history tracking. Removing those duplicates could reduce reported volume. Repository history does not prove how many duplicates occurred, the GA4 stream's historical settings, or the exact production deployment time. The September 25 drop therefore remains a reporting investigation, not a reproduced navigation failure. Jonny should compare event counts and stream settings around the deployment before treating the old 6 to 7 views per user as a required baseline. + +Relevant files: `src/routes/__root.tsx`, `src/utils/analytics.ts`, `src/utils/analytics/providers/google.ts`, `.agents/analytics.md`. + +## Step 5: Partner parameter security review + +### Where values originate + +The site's partner click handlers take `partner_id` and `partner_tier` from the source-controlled catalog in `src/utils/partners.tsx`. Placements come from component props supplied by application code or string literals. Destinations are the fixed values `external`, `internal_detail`, and `internal_resource`. Destination hosts come from configured partner/resource URLs. `page_type` is calculated from `window.location.pathname` using a fixed set of return values in `src/utils/analytics.ts`. + +The `/partners/$partner` route does accept a path parameter, but resolves it through `findPartnerForPage` and `getPartnerById`, which perform an in-memory lookup in that catalog. Unknown IDs produce a not-found response. The click event uses the matched catalog object's ID, not the raw URL parameter. Directory search filters do not supply the reported click fields. + +Reviewed click callers include `PartnersGrid`, `PartnerRail`, `LibraryLayout`, `StartHostingPartners`, `IslandInfo3D`, the partner directory, the generic partner detail route, and the Render, Railway, and Netlify detail routes. None reads these click fields directly from query strings, forms, or request bodies. + +### Server and database path + +GA4 events do reach TanStack's server. The GA configuration uses `transport_url` with the same-origin `/_a` prefix. `proxyAnalyticsRequest` in `src/server.ts` receives `/_a/g/collect` and forwards its query string and body to the fixed upstream `https://www.google-analytics.com/g/collect`. + +That proxy does not interpolate event fields into SQL, execute them, or write them to a TanStack database. Its response returns before the application route handler runs. The surrounding `runWithDatabaseContext` establishes lazy request context, but does not itself execute a query. No server-side partner-click persistence or database consumer was found. Request diagnostics record the request pathname and status, not partner event parameters. + +The collection proxy currently does not validate partner fields against a runtime allowlist. TypeScript types constrain application call sites, but do not validate a direct HTTP request from a scanner. A scanner can submit forged analytics payloads to the public proxy or directly to Google's public collection endpoint. Strings such as `sleep(15)` in GA4 are therefore consistent with analytics pollution; their presence alone does not establish SQL execution or identify the scanner's entry point. + +The reviewed path has no SQL sink requiring parameterization. This is a scoped review of partner event data flow, not a full application penetration test. Runtime allowlists can improve the quality of events sent by the app; filtering suspect events in reporting is still necessary because a client-side check cannot authenticate public analytics collection requests. + +## Step 6: Privacy review + +The current policy in `src/routes/privacy.tsx`, effective September 28, already names Scarf, page views, external link clicks, downloads, and copy/paste collection. It also describes sharing with analytics service providers. This covers the general activity involved in outbound partner tracking. + +Per the final scope, no per-partner Scarf pixels are installed. The policy now also lists hover intent among the actions sent to Scarf. The existing namethathost.com description should not be treated as a description of Scarf's processing. + +This is a review of the policy's wording against the implementation, not a determination of legal compliance. The existing copy/paste feature can transmit user-provided text, so a general statement that all tracking is non-personal data would not match the implementation. + +## Verification still needed + +- Jonny's GA4 DebugView and BigQuery checks, including comparison of stream settings and the deployment window around September 25. +- Production verification of the new Scarf pixel IDs and placements after deployment. +- The actual production deployment timestamp in UTC and the final pixel-name-to-ID list for Jonny. + +## Implementation scope + +Scarf page pixels cover the home page, all 18 publicly listed libraries, and Application Starter, Builder, NPM Stats, and Intent Registry. Existing Ranger tracking remains. Hidden MCP and Workflow have no new pixels. The shared library route covers landing pages and docs; resolved navigation and a fresh cache-busting UUID prevent cross-library attribution and cached Back visits. + +The existing site-events endpoint also receives `external_link_hover_intent` after 350 ms over an external HTTP(S) link. Moving within a link does not duplicate the event. Leaving, changing pages, backgrounding, or removing the link cancels it. The payload contains the page path and destination origin/path, with destination query strings and fragments omitted. + +Partner click pixels were excluded by Tanner's scope correction. None is installed in this change. The 13 accidentally created dashboard pixels are awaiting explicit permanent-deletion confirmation, required by automatic approval review. + +## New page pixels + +| Pixel name | ID | +| -------------------------------- | ------------------------------------ | +| Home Page | b7a8c111-2305-4d95-a02a-d84c5bfb82ae | +| Docs – DB | 893a4852-11b6-4138-8206-7f06a11591e4 | +| Docs – Pacer | 4f87da04-9555-4078-bea5-097562fda71a | +| tanstack.com/charts | aa0a3a1f-ffb1-4a50-b57f-c904dfc003d6 | +| tanstack.com/hotkeys | 1bd669b3-a148-4551-967f-1b9d2c971a2c | +| tanstack.com/markdown | bcf17c55-0fa4-4bcb-be21-823711b0b7fd | +| tanstack.com/highlight | 755a8d7a-458b-421d-aef3-dc85437ac0bd | +| tanstack.com/ai | c627cc8f-28a1-4b5d-bd13-9142a7fb4172 | +| tanstack.com/intent | 9a861dfa-93fb-4472-b462-2cdadbe3a717 | +| tanstack.com/config | 6e4c7302-6e7d-45ec-b963-9ac66c70c6b2 | +| tanstack.com/devtools | 9383bf22-a41e-477f-8dc2-fca9d2a201b7 | +| tanstack.com/cli | a1a4961c-5b37-43eb-a6fc-7e4825fbe83b | +| tanstack.com/application-starter | ed471ec3-aa08-430f-8481-258b3a1f94dc | +| tanstack.com/builder | aa4dcee9-86a2-49b4-9981-40c97cc1f55b | +| tanstack.com/stats/npm | e729f879-e127-48e1-be19-c68f6786c9e8 | +| tanstack.com/intent/registry | 811c34af-38bd-4f06-9762-3f58dea0650a | + +DB and Pacer retain the names from the handoff, but their pixels cover landing pages as well as docs. + +## Local validation + +- Full `pnpm test`: passed, 525 tests passed and 3 skipped; TypeScript passed; lint reported one existing warning in `src/utils/repo-path.ts`. +- Added a catalog check requiring a pixel for every public library and preventing duplicate library pixel IDs. Targeted test passed. +- Browser: home renders only the Home Page pixel; Query landing and docs render only Query; navigating Back creates a fresh URL; DB and Pacer each render their own pixel; NPM Stats, Intent Registry, Builder, and Application Starter each use their product pixel. +- Hover tracking passed 13 targeted event/timer scenarios, including child movement, leave-before-delay, navigation, backgrounding, removed links, and cleanup. diff --git a/src/components/ProductScarf.tsx b/src/components/ProductScarf.tsx new file mode 100644 index 000000000..c37c50416 --- /dev/null +++ b/src/components/ProductScarf.tsx @@ -0,0 +1,22 @@ +import { useRouterState } from '@tanstack/react-router' +import { Scarf } from './Scarf' + +const products = [ + { path: '/application-starter', id: 'ed471ec3-aa08-430f-8481-258b3a1f94dc' }, + { path: '/builder', id: 'aa4dcee9-86a2-49b4-9981-40c97cc1f55b' }, + { path: '/stats/npm', id: 'e729f879-e127-48e1-be19-c68f6786c9e8' }, + { path: '/intent/registry', id: '811c34af-38bd-4f06-9762-3f58dea0650a' }, +] + +export function ProductScarf() { + const product = useRouterState({ + select: (state) => { + const pathname = state.resolvedLocation?.pathname + return products.find( + ({ path }) => pathname === path || pathname?.startsWith(`${path}/`), + ) + }, + }) + + return product ? : null +} diff --git a/src/components/Scarf.tsx b/src/components/Scarf.tsx index e6c5128a0..f68d4b01e 100644 --- a/src/components/Scarf.tsx +++ b/src/components/Scarf.tsx @@ -1,18 +1,46 @@ import { useRouterState } from '@tanstack/react-router' -import { useMounted } from '~/hooks/useMounted' +import { useEffect, useRef, useState } from 'react' -export function Scarf({ id }: { id: string }) { - const locationKey = useRouterState({ select: (s) => s.location.state.key }) +export function Scarf({ id, path }: { id: string; path: string }) { + const visit = useRouterState({ + select: (state) => { + const location = state.resolvedLocation + if ( + state.status !== 'idle' || + !location || + location.href !== state.location.href || + (location.pathname !== path && + (path === '/' || !location.pathname.startsWith(`${path}/`))) + ) { + return null + } - const mounted = useMounted() + return `${id}:${location.state.key}:${location.href}` + }, + }) + const lastVisit = useRef(null) + const [pixel, setPixel] = useState<{ visit: string; src: string } | null>( + null, + ) - return mounted ? ( + useEffect(() => { + if (!visit || lastVisit.current === visit) return + lastVisit.current = visit + setPixel({ + visit, + src: `https://static.scarf.sh/a.png?x-pxid=${encodeURIComponent(id)}&key=${crypto.randomUUID()}`, + }) + }, [id, visit]) + + return pixel && pixel.visit === visit ? ( scarf analytics ) : null } diff --git a/src/libraries/libraries.ts b/src/libraries/libraries.ts index db29081f5..06a5682b9 100644 --- a/src/libraries/libraries.ts +++ b/src/libraries/libraries.ts @@ -335,6 +335,7 @@ export const table: LibrarySlim = { export const charts: LibrarySlim = { id: 'charts', + scarfId: 'aa0a3a1f-ffb1-4a50-b57f-c904dfc003d6', ...categoryStyles.ui, name: 'TanStack Charts', to: '/charts/latest', @@ -547,7 +548,7 @@ export const pacer: LibrarySlim = { latestVersion: 'v0', latestBranch: 'main', availableVersions: ['v0'], - scarfId: '302d0fef-cb3f-43c6-b45c-f055b9745edb', + scarfId: '4f87da04-9555-4078-bea5-097562fda71a', defaultDocs: 'overview', sitemap: { includeLandingPage: true, @@ -571,6 +572,7 @@ export const pacer: LibrarySlim = { export const hotkeys: LibrarySlim = { id: 'hotkeys', + scarfId: '1bd669b3-a148-4551-967f-1b9d2c971a2c', ...categoryStyles.performance, name: 'TanStack Hotkeys', to: '/hotkeys/latest', @@ -604,6 +606,7 @@ export const hotkeys: LibrarySlim = { export const markdown: LibrarySlim = { id: 'markdown', + scarfId: 'bcf17c55-0fa4-4bcb-be21-823711b0b7fd', name: 'TanStack Markdown', cardStyles: 'text-fuchsia-500 dark:text-fuchsia-400 hover:border-current', to: '/markdown/latest', @@ -634,6 +637,7 @@ export const markdown: LibrarySlim = { export const highlight: LibrarySlim = { id: 'highlight', + scarfId: '755a8d7a-458b-421d-aef3-dc85437ac0bd', name: 'TanStack Highlight', cardStyles: 'text-amber-500 dark:text-amber-400 hover:border-current', to: '/highlight/latest', @@ -678,7 +682,7 @@ export const db: LibrarySlim = { latestVersion: 'v0', latestBranch: 'main', availableVersions: ['v0'], - scarfId: '302d0fef-cb3f-43c6-b45c-f055b9745edb', + scarfId: '893a4852-11b6-4138-8206-7f06a11591e4', defaultDocs: 'overview', sitemap: { includeLandingPage: true, @@ -688,6 +692,7 @@ export const db: LibrarySlim = { export const ai: LibrarySlim = { id: 'ai', + scarfId: 'c627cc8f-28a1-4b5d-bd13-9142a7fb4172', ...categoryStyles.data, name: 'TanStack AI', to: '/ai/latest', @@ -741,6 +746,7 @@ export const ai: LibrarySlim = { export const intent: LibrarySlim = { id: 'intent', + scarfId: '9a861dfa-93fb-4472-b462-2cdadbe3a717', ...categoryStyles.tooling, name: 'TanStack Intent', to: '/intent/latest', @@ -764,6 +770,7 @@ export const intent: LibrarySlim = { export const config: LibrarySlim = { id: 'config', + scarfId: '6e4c7302-6e7d-45ec-b963-9ac66c70c6b2', ...categoryStyles.tooling, name: 'TanStack Config', to: '/config/latest', @@ -787,6 +794,7 @@ export const config: LibrarySlim = { export const devtools: LibrarySlim = { id: 'devtools', + scarfId: '9383bf22-a41e-477f-8dc2-fca9d2a201b7', ...categoryStyles.tooling, name: 'TanStack Devtools', to: '/devtools/latest', @@ -851,6 +859,7 @@ export const mcp: LibrarySlim = { export const cli: LibrarySlim = { id: 'cli', + scarfId: 'a1a4961c-5b37-43eb-a6fc-7e4825fbe83b', ...categoryStyles.tooling, name: 'TanStack CLI', to: '/cli/latest', diff --git a/src/routes/__root.tsx b/src/routes/__root.tsx index 31a7a1a01..e60ba250d 100644 --- a/src/routes/__root.tsx +++ b/src/routes/__root.tsx @@ -39,6 +39,7 @@ import { Spinner } from '~/components/Spinner' import { ThemeProvider, useHtmlClass } from '~/components/ThemeProvider' import { Navbar } from '~/components/Navbar' import { Footer } from '~/components/Footer' +import { ProductScarf } from '~/components/ProductScarf' import { BuilderRouteFrame, BuilderRouteSkeleton, @@ -49,6 +50,7 @@ import { trackScarfClipboardEvent, trackScarfDownloadClick, trackScarfExternalLinkClick, + trackScarfExternalLinkHoverIntent, trackScarfPageView, } from '~/utils/analytics/scarf' import { createPartnerPlacementSessionSeed } from '~/utils/partner-placement' @@ -363,6 +365,7 @@ function ShellComponent({ children }: { children: React.ReactNode }) { + {hideNavbar ? ( routeContent @@ -441,11 +444,13 @@ function PageViewTracker() { const lastTrackedPath = React.useRef(null) React.useEffect(() => { + const stopTrackingHoverIntent = trackScarfExternalLinkHoverIntent() document.addEventListener('click', trackScarfExternalLinkClick, true) document.addEventListener('click', trackScarfDownloadClick, true) document.addEventListener('copy', trackScarfClipboardEvent, true) document.addEventListener('paste', trackScarfClipboardEvent, true) return () => { + stopTrackingHoverIntent() document.removeEventListener('click', trackScarfExternalLinkClick, true) document.removeEventListener('click', trackScarfDownloadClick, true) document.removeEventListener('copy', trackScarfClipboardEvent, true) diff --git a/src/routes/_library.tsx b/src/routes/_library.tsx index 00dbcf0b9..f2bad9a5d 100644 --- a/src/routes/_library.tsx +++ b/src/routes/_library.tsx @@ -5,6 +5,7 @@ import { useMatches, } from '@tanstack/react-router' import { LibraryLayout } from '~/components/LibraryLayout' +import { Scarf } from '~/components/Scarf' import { findLibrary } from '~/libraries' import type { LibraryId } from '~/libraries' import type { ConfigSchema } from '~/utils/config' @@ -74,6 +75,9 @@ function LibraryRoute() { isLandingPage={layoutData.isLandingPage} > + {library.scarfId ? ( + + ) : null} ) } diff --git a/src/routes/_library/$libraryId/route.tsx b/src/routes/_library/$libraryId/route.tsx index 5f0202edd..b8831c78b 100644 --- a/src/routes/_library/$libraryId/route.tsx +++ b/src/routes/_library/$libraryId/route.tsx @@ -1,6 +1,5 @@ import { createFileRoute } from '@tanstack/react-router' import { notFound, Outlet } from '@tanstack/react-router' -import { Scarf } from '~/components/Scarf' import { findLibrary, LibraryId } from '~/libraries' import { seo } from '~/utils/seo' import { ogImageUrl } from '~/utils/og' @@ -65,10 +64,5 @@ function RouteForm() { return null } - return ( - <> - - {library?.scarfId ? : null} - - ) + return } diff --git a/src/routes/index.tsx b/src/routes/index.tsx index 04924831c..6e99ade82 100644 --- a/src/routes/index.tsx +++ b/src/routes/index.tsx @@ -21,6 +21,7 @@ import { HomeStatsSection } from '~/components/home/HomeStatsSection' import { useQuery } from '@tanstack/react-query' import { Button, Eyebrow } from '~/components/ds/ui' import { Squircle } from '~/components/Squircle' +import { Scarf } from '~/components/Scarf' import { useInView } from '~/hooks/useInView' import { useNpmDownloadCounter } from '~/hooks/useNpmDownloadCounter' import { homepageNpmStatsSummaryQuery, ossStatsQuery } from '~/queries/stats' @@ -75,6 +76,7 @@ function Index() { return ( <> +
{/* Hero — Figma node 802:2027. Full-bleed palm/gradient photo card: diff --git a/src/routes/privacy.tsx b/src/routes/privacy.tsx index 4095eba70..1c160da6f 100644 --- a/src/routes/privacy.tsx +++ b/src/routes/privacy.tsx @@ -80,11 +80,11 @@ function RouteComp() {

3. Cookies and Tracking

We use Scarf to measure page views and actions on the Site, - including external link clicks, downloads, and copy and paste. For - copy and paste events, we send the first 512 characters of plain - text along with the page path. This text may include information you - choose to copy or paste. We do not collect text from password fields - for these events. + including external link clicks, hover intent, downloads, and copy + and paste. For copy and paste events, we send the first 512 + characters of plain text along with the page path. This text may + include information you choose to copy or paste. We do not collect + text from password fields for these events.

We use namethathost.com, operated by TanStack, to understand which diff --git a/src/utils/analytics/scarf.ts b/src/utils/analytics/scarf.ts index e68447b44..ad87346cf 100644 --- a/src/utils/analytics/scarf.ts +++ b/src/utils/analytics/scarf.ts @@ -36,7 +36,9 @@ export const scarfAnalyticsProvider: AnalyticsProvider = { action: String(properties.action), surface: String(properties.surface), automatic: String(properties.automatic), - ...(properties.provider ? { provider: String(properties.provider) } : {}), + ...(properties.provider + ? { provider: String(properties.provider) } + : {}), }) } else if (event === 'partner_inquiry_started') { sendScarfEvent(event, { @@ -121,6 +123,18 @@ export function trackScarfDownloadClick(event: MouseEvent) { sendScarfEvent('download_requested', { page: window.location.pathname }) } +function getExternalLinkDestination(link: HTMLAnchorElement) { + const destination = new URL(link.href, window.location.href) + if ( + !['http:', 'https:'].includes(destination.protocol) || + destination.origin === window.location.origin + ) { + return null + } + + return `${destination.origin}${destination.pathname}` +} + export function trackScarfExternalLinkClick(event: MouseEvent) { const target = event.target if (!(target instanceof Element)) return @@ -128,16 +142,86 @@ export function trackScarfExternalLinkClick(event: MouseEvent) { const link = target.closest('a[href]') if (!(link instanceof HTMLAnchorElement)) return - const destination = new URL(link.href, window.location.href) - if ( - !['http:', 'https:'].includes(destination.protocol) || - destination.origin === window.location.origin - ) { - return - } + const destination = getExternalLinkDestination(link) + if (!destination) return sendScarfEvent('external_link_click', { page: window.location.pathname, - destination: `${destination.origin}${destination.pathname}`, + destination, }) } + +export function trackScarfExternalLinkHoverIntent() { + let hoveredLink: HTMLAnchorElement | null = null + let timer: ReturnType | undefined + + const cancelHover = () => { + clearTimeout(timer) + hoveredLink = null + } + + const onPointerOver = (event: PointerEvent) => { + if (event.pointerType === 'touch' || !(event.target instanceof Element)) { + return + } + + const link = event.target.closest('a[href]') + if (!(link instanceof HTMLAnchorElement) || link === hoveredLink) return + + const destination = getExternalLinkDestination(link) + if (!destination) return + + clearTimeout(timer) + hoveredLink = link + const page = window.location.href + const navigationKey = window.history.state?.key + timer = setTimeout(() => { + if ( + !link.isConnected || + document.visibilityState !== 'visible' || + window.location.href !== page || + window.history.state?.key !== navigationKey || + getExternalLinkDestination(link) !== destination + ) { + cancelHover() + return + } + + sendScarfEvent('external_link_hover_intent', { + page: window.location.pathname, + destination, + }) + }, 350) + } + + const onPointerOut = (event: PointerEvent) => { + if ( + hoveredLink && + event.target instanceof Node && + hoveredLink.contains(event.target) && + !( + event.relatedTarget instanceof Node && + hoveredLink.contains(event.relatedTarget) + ) + ) { + cancelHover() + } + } + + document.addEventListener('pointerover', onPointerOver, true) + document.addEventListener('pointerout', onPointerOut, true) + document.addEventListener('visibilitychange', cancelHover) + window.addEventListener('blur', cancelHover) + window.addEventListener('pagehide', cancelHover) + window.addEventListener('popstate', cancelHover) + + return () => { + cancelHover() + document.removeEventListener('pointerover', onPointerOver, true) + document.removeEventListener('pointerout', onPointerOut, true) + document.removeEventListener('visibilitychange', cancelHover) + window.removeEventListener('blur', cancelHover) + window.removeEventListener('pagehide', cancelHover) + window.removeEventListener('popstate', cancelHover) + } +} diff --git a/tests/static-data-contracts.test.ts b/tests/static-data-contracts.test.ts index ff0633a38..eb38a11d8 100644 --- a/tests/static-data-contracts.test.ts +++ b/tests/static-data-contracts.test.ts @@ -28,6 +28,7 @@ assert.equal( ) for (const library of publicLibraries) { + assert.ok(library.scarfId, `${library.id} must have a Scarf pixel`) assert.equal( library.to.startsWith('/'), true, @@ -40,6 +41,15 @@ for (const library of publicLibraries) { ) } +const scarfIds = libraries.flatMap((library) => + library.scarfId ? [library.scarfId] : [], +) +assert.equal( + new Set(scarfIds).size, + scarfIds.length, + 'Each library must use its own Scarf pixel', +) + for (const library of libraries) { if (!library.scarfId) { continue