chore: simplify guardrails and clear lint warnings

Author: tannerlinsley

docs/source-code-audit-2026-06-23.md

@@ -17,9 +17,11 @@ These are quick, high-leverage patches because later fixes can reuse them instea
 - [done 2026-06-24: `pnpm run test:unit`, `pnpm test`] Make `pnpm test` honest about TypeScript tests, or split script names so validation expectations are clear.
 - [done 2026-06-24: `pnpm run test:tsc`, `pnpm run test:lint`] Default non-submit buttons/select triggers to `type="button"`, fix the shared pagination label/id contract, and clean up tooltip child prop merging.
 - [done 2026-06-24: `pnpm run test:unit`, `pnpm run test:tsc`, `pnpm run test:lint`] Add tiny helpers for response filenames, package slug encoding, and row-local ids.
-- Add tiny helpers for external URL normalization, internal route classification, and guarded storage.
-- Fix custom `useMutation` stale callbacks, clipboard/copied-state timers, docs sidebar timers, popup blocked-state handling, and simple page-visibility/reduced-motion helpers.
-- Normalize easy static data contracts: maintainer bare-domain URLs, Scarf id validation, public-library selector, partner analytics seed buckets, blog image URLs, host cache purge response policy.
+- [done 2026-06-24: `pnpm test`, 60-route local smoke] Add tiny helpers for external URL normalization, internal route classification, and guarded storage.
+- [done 2026-06-24: `pnpm test`, 60-route local smoke] Share low-risk clipboard/copy-state timers and auth popup centering.
+- Fix custom `useMutation` stale callbacks, docs sidebar timers, remaining popup blocked-state handling, and remaining page-visibility/reduced-motion call sites.
+- [done 2026-06-24: `pnpm test`, 60-route local smoke] Normalize maintainer bare-domain URLs, add Scarf/social URL contract tests, and centralize the public-library selector.
+- Normalize partner analytics seed buckets, blog image URLs, and host cache purge response policy.
 
 ### 2. One-off cleanup that lowers noise
 
@@ -94,6 +96,7 @@ Treat these as tracked initiatives, not normal cleanup PRs.
 - 2026-06-24: Added shared response filename/content-disposition helpers, package route slug encoding helpers, and row-local id helpers; wired them into builder/docs downloads, Intent registry links, and moderation note inputs.
 - 2026-06-24: Hardened shared UI primitives: defaulted shop buttons and shared select triggers to non-submit buttons, gave pagination a unique page-size label/id pair plus non-submit controls, and made Tooltip merge trigger handlers/refs without `any`.
 - 2026-06-24: Added `test:unit` and wired it into `pnpm test` so existing TypeScript assertion tests run in the default validation path.
+- 2026-06-24: Added guarded browser storage/effect helpers, migrated low-risk clipboard/timer/popup/storage/reduced-motion call sites, centralized public-library selection, normalized maintainer URLs, and added static data contract tests.
 - 2026-06-23: Audit created and ordered.
 
 ## Highest Priority Findings
@@ -2185,7 +2188,7 @@ This is a strong candidate for a reusable TanStack docs-site cache helper or at
 
 ### Good pattern: slim data modules with explicit heavy-data escape hatches
 
-`src/libraries/libraries.ts:1-2` keeps base library data lightweight, while `src/libraries/index.tsx:34-44` explicitly avoids re-exporting extended per-library landing-page projects that contain React nodes and heavier assets. This is the right shape for global navigation/docs data: a slim default import path plus opt-in heavy modules for routes that actually render the full experience.
+`src/libraries/libraries.ts:1-2` keeps base library data lightweight, while `src/libraries/index.tsx:34-44` explicitly avoids re-exporting extended per-library landing-page projects that contain React nodes and heavier assets. `publicLibraries` and `isPublicLibrary` now give navigation/search/API callers one shared public catalog boundary. This is the right shape for global navigation/docs data: a slim default import path plus opt-in heavy modules for routes that actually render the full experience.
 
 ### Good pattern: lazy activation for expensive navbar features
 
@@ -2208,6 +2211,7 @@ This is a strong candidate for a reusable TanStack docs-site cache helper or at
 - Builder definition schema shared between client UI, validate, compile, download, deploy, and MCP.
 - A deploy-dialog controller shared by builder-generated projects and docs example deployment.
 - React/browser effect helpers for timed flags, popup polling, clipboard writes, guarded storage, outside-click behavior, and drag-resize listeners.
+- Static data contract tests for public catalogs, maintainer/social URLs, package metadata IDs, and other small hand-authored data tables.
 - An OAuth PKCE helper with atomic code consumption patterns for Drizzle/Postgres.
 - A first-party OAuth callback helper that validates provider params, clears transient cookies on every exit, and normalizes provider token/profile responses.
 - A React Query query-options linter/helper that asserts query keys include every query-function input.

src/auth/client.ts

@@ -6,6 +6,7 @@
  */
 
 import type { OAuthProvider } from './types'
+import { openCenteredPopupWindow } from '~/utils/browser-effects'
 
 // ============================================================================
 // Auth Client
@@ -36,15 +37,13 @@ export const authClient = {
      * Initiate OAuth sign-in in a popup window (for modal-based login)
      */
     socialPopup: ({ provider }: { provider: OAuthProvider }) => {
-      const width = 500
-      const height = 600
-      const left = window.screenX + (window.outerWidth - width) / 2
-      const top = window.screenY + (window.outerHeight - height) / 2
-      return window.open(
-        `/auth/${provider}/start?popup=true`,
-        'tanstack-oauth',
-        `width=${width},height=${height},left=${left},top=${top},popup=yes`,
-      )
+      return openCenteredPopupWindow({
+        url: `/auth/${provider}/start?popup=true`,
+        target: 'tanstack-oauth',
+        width: 500,
+        height: 600,
+        features: ['popup=yes'],
+      })
     },
   },
 

src/components/BrandContextMenu.tsx

@@ -9,6 +9,7 @@ import {
   DropdownItem,
   DropdownSeparator,
 } from './Dropdown'
+import { copyTextToClipboard } from '~/utils/browser-effects'
 
 interface BrandContextMenuProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode
@@ -32,7 +33,7 @@ export function BrandContextMenu({ children, ...rest }: BrandContextMenuProps) {
 
   const copyText = async (text: string) => {
     try {
-      await navigator.clipboard.writeText(text)
+      await copyTextToClipboard(text)
       notify(
         <div>
           <div className="font-medium">Copied to clipboard</div>

src/components/CopyMarkdownButton.tsx

@@ -1,30 +1,16 @@
 'use client'
-import { type MouseEventHandler, useEffect, useRef, useState } from 'react'
+import { type MouseEventHandler } from 'react'
+import { useTemporaryFlag } from '~/utils/browser-effects'
 
 export function useCopyButton(
   onCopy: () => void | Promise<void>,
 ): [checked: boolean, onClick: MouseEventHandler] {
-  const [checked, setChecked] = useState(false)
-  const timeoutRef = useRef<number | null>(null)
+  const copied = useTemporaryFlag(1500)
 
   const onClick: MouseEventHandler = async () => {
-    if (timeoutRef.current) window.clearTimeout(timeoutRef.current)
-    const res = Promise.resolve(onCopy())
-
-    void res.then(() => {
-      setChecked(true)
-      timeoutRef.current = window.setTimeout(() => {
-        setChecked(false)
-      }, 1500)
-    })
+    await onCopy()
+    copied.trigger()
   }
 
-  // avoid updates after being unmounted
-  useEffect(() => {
-    return () => {
-      if (timeoutRef.current) window.clearTimeout(timeoutRef.current)
-    }
-  }, [])
-
-  return [checked, onClick]
+  return [copied.active, onClick]
 }

src/components/CopyPageDropdown.tsx

@@ -11,6 +11,12 @@ import {
   DropdownItem,
 } from './Dropdown'
 import { getPackageManager } from '~/utils/markdown/installCommand'
+import {
+  copyTextToClipboard,
+  openPopupWindow,
+  useTemporaryFlag,
+} from '~/utils/browser-effects'
+import { getLocalStorageItem } from '~/utils/browser-storage'
 
 // Markdown icon component matching the screenshot
 function MarkdownIcon({ className }: { className?: string }) {
@@ -110,25 +116,26 @@ export function CopyPageDropdown({
   label = 'Copy page',
 }: CopyPageDropdownProps = {}) {
   const [open, setOpen] = React.useState(false)
-  const [copied, setCopied] = React.useState(false)
+  const copied = useTemporaryFlag()
   const { notify } = useToast()
 
   // For docs pages in this repo, prefer the site's markdown endpoint so requests stay behind site caching.
   const pageMarkdownUrl = (() => {
-    const base = `${typeof window !== 'undefined' ? window.location.origin : ''}${typeof window !== 'undefined' ? window.location.pathname.replace(/\/$/, '') : ''}.md`
-    const params =
-      typeof window !== 'undefined'
-        ? new URLSearchParams(window.location.search)
-        : new URLSearchParams()
+    if (typeof window === 'undefined') {
+      return '.md'
+    }
+
+    const base = `${window.location.origin}${window.location.pathname.replace(/\/$/, '')}.md`
+    const params = new URLSearchParams(window.location.search)
     if (currentFramework) {
       params.set('framework', currentFramework)
     }
+
     // Read package manager from localStorage (same key as PackageManagerTabs)
-    if (typeof localStorage !== 'undefined') {
-      const pm = localStorage.getItem('packageManager')
-      const validPm = getPackageManager(pm)
-      params.set('pm', validPm)
-    }
+    const pm = getLocalStorageItem('packageManager')
+    const validPm = getPackageManager(pm)
+    params.set('pm', validPm)
+
     const queryString = params.toString()
     return queryString ? `${base}?${queryString}` : base
   })()
@@ -142,9 +149,8 @@ export function CopyPageDropdown({
 
   const handleCopyPage = async () => {
     if (rawContent) {
-      await navigator.clipboard.writeText(rawContent)
-      setCopied(true)
-      setTimeout(() => setCopied(false), 2000)
+      await copyTextToClipboard(rawContent)
+      copied.trigger()
       notify(
         <div>
           <div className="font-medium">Copied to clipboard</div>
@@ -157,9 +163,8 @@ export function CopyPageDropdown({
     const cached = markdownCache.get(urlToFetch)
 
     const copyContent = async (content: string, source: string) => {
-      await navigator.clipboard.writeText(content)
-      setCopied(true)
-      setTimeout(() => setCopied(false), 2000)
+      await copyTextToClipboard(content)
+      copied.trigger()
       notify(
         <div>
           <div className="font-medium">Copied to clipboard</div>
@@ -194,9 +199,8 @@ export function CopyPageDropdown({
         await copyContent(pageContent, 'Copied rendered page content')
       } else {
         // Last resort: copy the URL
-        await navigator.clipboard.writeText(window.location.href)
-        setCopied(true)
-        setTimeout(() => setCopied(false), 2000)
+        await copyTextToClipboard(window.location.href)
+        copied.trigger()
         notify(
           <div>
             <div className="font-medium">Copied to clipboard</div>
@@ -211,33 +215,32 @@ export function CopyPageDropdown({
 
   const handleViewMarkdown = () => {
     const url = sourceMarkdownUrl
-    window.open(url, '_blank')
+    openPopupWindow(url)
   }
 
   const handleOpenInClaude = () => {
     const pageUrl = window.location.href
     const prompt = encodeURIComponent(
       `Read from this URL: ${pageUrl} and explain it to me`,
     )
-    window.open(`https://claude.ai/new?q=${prompt}`, '_blank')
+    openPopupWindow(`https://claude.ai/new?q=${prompt}`)
   }
 
   const handleOpenInChatGPT = () => {
     const pageUrl = window.location.href
     const prompt = encodeURIComponent(
       `Read from this URL: ${pageUrl} and explain it to me`,
     )
-    window.open(`https://chatgpt.com/?q=${prompt}`, '_blank')
+    openPopupWindow(`https://chatgpt.com/?q=${prompt}`)
   }
 
   const handleOpenInCursor = () => {
     const pageUrl = window.location.href
     const prompt = `Read from this URL:\n${pageUrl}\nand explain it to me`
-    window.open(
+    openPopupWindow(
       `cursor://anysphere.cursor-deeplink/prompt?text=${encodeURIComponent(
         prompt,
       )}`,
-      '_blank',
     )
   }
 
@@ -246,7 +249,7 @@ export function CopyPageDropdown({
     const prompt = encodeURIComponent(
       `Read from this URL: ${pageUrl} and explain it to me`,
     )
-    window.open(`https://t3.chat/new?q=${prompt}`, '_blank')
+    openPopupWindow(`https://t3.chat/new?q=${prompt}`)
   }
 
   const menuItems = [
@@ -289,13 +292,14 @@ export function CopyPageDropdown({
   return (
     <ButtonGroup>
       <Button
+        type="button"
         variant="ghost"
         size="xs"
         rounded="none"
         className="border-0"
         onClick={handleCopyPage}
       >
-        {copied ? (
+        {copied.active ? (
           <>
             <Check className="w-3 h-3" />
             Copied!
@@ -310,6 +314,7 @@ export function CopyPageDropdown({
       <Dropdown open={open} onOpenChange={setOpen}>
         <DropdownTrigger>
           <Button
+            type="button"
             variant="ghost"
             size="xs"
             rounded="none"

src/components/FrameworkCard.tsx

@@ -10,6 +10,7 @@ import {
   getFrameworkDocsHash,
   getFrameworkDocsPath,
 } from '~/libraries/frameworkSupport'
+import { copyTextToClipboard } from '~/utils/browser-effects'
 
 export function FrameworkCard({
   framework,
@@ -28,7 +29,7 @@ export function FrameworkCard({
 }) {
   const { notify } = useToast()
   const [copied, onCopyClick] = useCopyButton(async () => {
-    await navigator.clipboard.writeText(packageName)
+    await copyTextToClipboard(packageName)
     notify(
       <div>
         <div className="font-medium">Copied package name</div>

src/components/FrameworkSelect.tsx

@@ -10,6 +10,10 @@ import {
   useCurrentUserQuery,
 } from '~/hooks/useCurrentUser'
 import { updateLastUsedFramework } from '~/utils/users.functions'
+import {
+  getLocalStorageItem,
+  setLocalStorageItem,
+} from '~/utils/browser-storage'
 
 function persistFrameworkToServer(framework: string) {
   void updateLastUsedFramework({ data: { framework } }).catch(() => {
@@ -51,12 +55,9 @@ export const useLocalCurrentFramework = create<{
   currentFramework?: string
   setCurrentFramework: (framework: string) => void
 }>((set) => ({
-  currentFramework:
-    typeof document !== 'undefined'
-      ? localStorage.getItem('framework') || undefined
-      : undefined,
+  currentFramework: getLocalStorageItem('framework') || undefined,
   setCurrentFramework: (framework: string) => {
-    localStorage.setItem('framework', framework)
+    setLocalStorageItem('framework', framework)
     set({ currentFramework: framework })
   },
 }))
@@ -66,8 +67,7 @@ export const useLocalCurrentFramework = create<{
  * Safe to call during SSR (returns undefined).
  */
 export function getStoredFrameworkPreference(): string | undefined {
-  if (typeof window === 'undefined') return undefined
-  return localStorage.getItem('framework') || undefined
+  return getLocalStorageItem('framework') || undefined
 }
 
 /**

src/components/LibrariesWidget.tsx

@@ -1,13 +1,10 @@
 import { Link } from '@tanstack/react-router'
-import { libraries } from '~/libraries'
+import { publicLibraries } from '~/libraries'
 
-const featuredLibraries = libraries
-  .filter((library) => library.visible !== false)
-  .slice(0, 8)
-  .map((library) => ({
-    id: library.id,
-    name: library.name,
-  }))
+const featuredLibraries = publicLibraries.slice(0, 8).map((library) => ({
+  id: library.id,
+  name: library.name,
+}))
 
 export function LibrariesWidget() {
   return (

src/components/LibraryLayout.tsx

@@ -1263,19 +1263,12 @@ export function LibraryLayout({
   const docsTabs = (
     <div className="sticky top-[var(--navbar-height)] z-30 border-b border-gray-500/20 bg-white/90 dark:bg-black/80 backdrop-blur-lg">
       <div className="flex items-stretch">
-        <label
-          htmlFor={mobileMenuToggleId}
-          role="button"
-          tabIndex={0}
+        <button
+          type="button"
           aria-label="Documentation menu"
           aria-expanded={mobileMenuOpen ? true : undefined}
           aria-controls="docs-mobile-menu"
-          onKeyDown={(event) => {
-            if (event.key === 'Enter' || event.key === ' ') {
-              event.preventDefault()
-              setMobileMenuOpen((prev) => !prev)
-            }
-          }}
+          onClick={() => setMobileMenuOpen((prev) => !prev)}
           data-docs-mobile-trigger
           className="min-[900px]:hidden flex items-center gap-1.5 shrink-0 px-3 border-r border-gray-500/20 text-slate-600 dark:text-slate-300 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-current"
         >
@@ -1284,7 +1277,7 @@ export function LibraryLayout({
           <span className="text-xs font-medium max-[479.98px]:sr-only">
             Menu
           </span>
-        </label>
+        </button>
         <button
           ref={largeMenuTriggerRef}
           type="button"