The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
feat: docs page formatting and coloring
ddux1c0f82debc0f
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex 76735534..124b2b60 100644--- a/docs/CLAUDE.md+++ b/docs/CLAUDE.md@@ -5,8 +5,11 @@- The header navbar items must always be aligned to the left (next to the logo), not centered or spread across the header. This is achieved via CSS in `styles/custom.css`.- Navbar order: Docs, Learn, Protocol, Self Host (controlled by key order in `pages/_meta.json`).-## SDK Query Parameter--- The `sdk` query parameter (e.g., `?sdk=go-gin`) must be sticky across all `/client` pages. When a user selects a framework, every sidebar link click and page navigation within `/client` must preserve the `sdk` param in the URL.-- This is handled by the `SdkProvider` in `components/SdkContext.jsx` which listens to route changes and re-injects the `sdk` param if missing.-- All internal links within `/client` pages should propagate `sdk` — do not create links that would drop the parameter.+## SDK Selection (path-derived)++- The URL **path is the single source of truth** for the active SDK. There is **no `?sdk=` query parameter** — do not reintroduce one, and never append `?sdk=` to internal `/client` links.+- `resolveSdkFromPath(pathname, lastSdk)` in `components/SdkContext.jsx` maps the first path segment after `/client/` to an SDK via `FOLDER_SDK`. Folders that map 1:1 to a framework (e.g. `gin-middleware` → `go-gin`, `react` → `js-react`) are authoritative.+- Two folders are shared/ambiguous (`SHARED_FOLDERS`): `sdk` (Go SDK Reference, any `go-*`) and `js-sdk` (JS SDK Reference, the JS frontend group). These disambiguate via the remembered framework in `localStorage['traceway-docs-sdk']` (`lastSdk`) when it belongs to the folder's group, otherwise fall back to `go-generic` / `js-generic`.+- `localStorage` stores only `lastSdk`. It is written when a specific SDK is resolved from the path, or when the user picks a framework from the dropdown (`SdkSelector`) or the `/client` picker (`FrameworkPicker`).+- Sidebar item visibility (`SDK_VISIBILITY` in `theme.config.jsx`) and the dropdown label both derive from the path-resolved SDK. `SDK_VISIBILITY` must stay complete (every `/client/<folder>` needs an entry) and matching is by exact first path segment, not substring.+- Stray `?sdk=` params on `/client` URLs are self-healed: `SdkProvider` strips them via a shallow `router.replace`, so old bookmarks/links correct themselves.diff --git a/docs/components/FrameworkPicker.jsx b/docs/components/FrameworkPicker.jsxindex ac00bb43..d1795780 100644--- a/docs/components/FrameworkPicker.jsx+++ b/docs/components/FrameworkPicker.jsx@@ -208,7 +208,7 @@ export default function FrameworkPicker() {function handleSelect(fw) {setSdk(fw.value);- router.push(`${fw.href}?sdk=${fw.value}`);+ router.push(fw.href);}return (diff --git a/docs/components/SdkContext.jsx b/docs/components/SdkContext.jsxindex 69acc0fb..da6ef43d 100644--- a/docs/components/SdkContext.jsx+++ b/docs/components/SdkContext.jsx@@ -31,10 +31,9 @@ export const SDK_OPTIONS = [const STORAGE_KEY = 'traceway-docs-sdk'const VALID_VALUES = new Set(SDK_OPTIONS.map((o) => o.value))-// IMPORTANT: longer/more-specific path segments must come before any shorter-// substring that would otherwise match first. `react-native` must precede-// `react`, otherwise `/client/react-native` would match `/react` first.-const PATH_SDK_MAP = {+// First path segment after /client/ → exact SDK value. These folders map 1:1+// to a single framework, so the path alone is authoritative.+const FOLDER_SDK = {'gin-middleware': 'go-gin','chi-middleware': 'go-chi','fiber-middleware': 'go-fiber',@@ -43,15 +42,15 @@ const PATH_SDK_MAP = {'node-sdk': 'js-node','nestjs': 'js-nestjs','hono': 'js-hono',- 'react-native': 'react-native',+ 'nextjs': 'js-nextjs','react': 'js-react',+ 'react-native': 'react-native','vue': 'js-vue','svelte': 'js-svelte','jquery': 'js-jquery','openrouter': 'openrouter','otel': 'otel','cloudflare': 'cloudflare',- 'nextjs': 'js-nextjs','symfony': 'php-symfony','laravel': 'php-laravel','django': 'python-django',@@ -59,110 +58,75 @@ const PATH_SDK_MAP = {'android': 'android',}+// Shared reference folders — the SDK cannot be derived from the path alone.+// Disambiguated by the remembered framework (lastSdk) when it belongs to the+// folder's group, otherwise by a generic fallback.+const SHARED_FOLDERS = {+ 'sdk': {+ members: new Set(['go-gin', 'go-chi', 'go-fiber', 'go-fasthttp', 'go-http', 'go-generic']),+ fallback: 'go-generic',+ },+ 'js-sdk': {+ members: new Set(['js-react', 'js-vue', 'js-svelte', 'js-jquery', 'js-generic']),+ fallback: 'js-generic',+ },+}++function clientSegment(pathname) {+ if (!pathname || !pathname.startsWith('/client')) return undefined+ return pathname.split('/').filter(Boolean)[1]+}++// The path is the single source of truth for the active SDK. `concrete` is true+// when the path unambiguously implies the SDK (so it should be remembered).+export function resolveSdkFromPath(pathname, lastSdk) {+ const seg = clientSegment(pathname)+ if (seg === undefined) return { sdk: null, concrete: false }+ if (FOLDER_SDK[seg]) return { sdk: FOLDER_SDK[seg], concrete: true }+ const shared = SHARED_FOLDERS[seg]+ if (shared) {+ if (lastSdk && shared.members.has(lastSdk)) return { sdk: lastSdk, concrete: false }+ return { sdk: shared.fallback, concrete: false }+ }+ return { sdk: null, concrete: false }+}+const SdkContext = createContext({- sdk: 'go-gin',+ sdk: null,setSdk: () => {},})export function SdkProvider({ children }) {const router = useRouter()- const [sdk, setSdkState] = useState('go-gin')+ const [sdk, setSdkState] = useState(null)useEffect(() => {- const params = new URLSearchParams(window.location.search)- const urlSdk = params.get('sdk')- if (urlSdk && VALID_VALUES.has(urlSdk)) {- setSdkState(urlSdk)- localStorage.setItem(STORAGE_KEY, urlSdk)- return+ const asPath = router.asPath+ const hashIdx = asPath.indexOf('#')+ const hash = hashIdx >= 0 ? asPath.slice(hashIdx) : ''+ const noHash = hashIdx >= 0 ? asPath.slice(0, hashIdx) : asPath+ const qIdx = noHash.indexOf('?')+ const pathname = qIdx >= 0 ? noHash.slice(0, qIdx) : noHash+ const params = new URLSearchParams(qIdx >= 0 ? noHash.slice(qIdx + 1) : '')++ const lastSdk = localStorage.getItem(STORAGE_KEY)+ const { sdk: resolved, concrete } = resolveSdkFromPath(pathname, lastSdk)+ if (resolved) {+ setSdkState(resolved)+ if (concrete && VALID_VALUES.has(resolved)) {+ localStorage.setItem(STORAGE_KEY, resolved)+ }}- const stored = localStorage.getItem(STORAGE_KEY)- if (stored && VALID_VALUES.has(stored)) {- setSdkState(stored)- }- }, [])-- useEffect(() => {- const params = new URLSearchParams(window.location.search)- const urlSdk = params.get('sdk')- if (urlSdk && VALID_VALUES.has(urlSdk) && urlSdk !== sdk) {- setSdkState(urlSdk)- localStorage.setItem(STORAGE_KEY, urlSdk)+ // Self-heal: strip any stray ?sdk= so /client URLs stay clean and old+ // bookmarks that pinned the wrong SDK correct themselves.+ if (pathname.startsWith('/client') && params.has('sdk')) {+ params.delete('sdk')+ const qs = params.toString()+ router.replace(pathname + (qs ? '?' + qs : '') + hash, undefined, { shallow: true })}}, [router.asPath])- // Keep sdk param sticky on all /client pages- useEffect(() => {- function handleRouteChange(url) {- if (!url.startsWith('/client')) return-- const hashIdx = url.indexOf('#')- const questionIdx = url.indexOf('?')-- let pathname, search, hash- if (hashIdx === -1 && questionIdx === -1) {- pathname = url; search = ''; hash = ''- } else if (questionIdx !== -1 && (hashIdx === -1 || questionIdx < hashIdx)) {- pathname = url.substring(0, questionIdx)- const rest = url.substring(questionIdx + 1)- const restHash = rest.indexOf('#')- if (restHash !== -1) {- search = rest.substring(0, restHash)- hash = rest.substring(restHash)- } else {- search = rest; hash = ''- }- } else {- pathname = url.substring(0, hashIdx)- const rest = url.substring(hashIdx)- const restQ = rest.indexOf('?')- if (restQ !== -1) {- hash = rest.substring(0, restQ)- search = rest.substring(restQ + 1)- } else {- hash = rest; search = ''- }- }-- const params = new URLSearchParams(search)-- if (pathname === '/client') {- if (params.has('sdk')) {- params.delete('sdk')- const qs = params.toString()- router.replace(pathname + (qs ? '?' + qs : '') + hash, undefined, { shallow: true })- }- localStorage.removeItem(STORAGE_KEY)- setSdkState('go-gin')- return- }-- if (!params.get('sdk')) {- let detectedSdk = null- for (const [folder, sdkValue] of Object.entries(PATH_SDK_MAP)) {- if (pathname.includes('/' + folder)) {- detectedSdk = sdkValue- break- }- }- const sdkToUse = detectedSdk || localStorage.getItem(STORAGE_KEY) || sdk- if (sdkToUse && VALID_VALUES.has(sdkToUse)) {- params.set('sdk', sdkToUse)- if (detectedSdk) {- setSdkState(detectedSdk)- localStorage.setItem(STORAGE_KEY, detectedSdk)- }- const qs = params.toString()- router.replace(pathname + (qs ? '?' + qs : '') + hash, undefined, { shallow: true })- }- }- }-- router.events.on('routeChangeComplete', handleRouteChange)- return () => router.events.off('routeChangeComplete', handleRouteChange)- }, [router, sdk])-const setSdk = useCallback((value) => {if (!VALID_VALUES.has(value)) returnsetSdkState(value)diff --git a/docs/components/SdkSelector.jsx b/docs/components/SdkSelector.jsxindex 61cec633..6e9ad377 100644--- a/docs/components/SdkSelector.jsx+++ b/docs/components/SdkSelector.jsx@@ -22,6 +22,8 @@ const SDK_QUICK_START = {'otel': '/client/otel','cloudflare': '/client/cloudflare','php-symfony': '/client/symfony',+ 'php-laravel': '/client/laravel',+ 'python-django': '/client/django','flutter': '/client/flutter','android': '/client/android','react-native': '/client/react-native',@@ -98,7 +100,7 @@ export default function SdkSelector() {setSearch('')const href = SDK_QUICK_START[option.value]if (href) {- router.push(`${href}?sdk=${option.value}`)+ router.push(href)}}}>diff --git a/docs/pages/client/android/index.mdx b/docs/pages/client/android/index.mdxindex 4ee05e2f..1b2cf4fe 100644--- a/docs/pages/client/android/index.mdx+++ b/docs/pages/client/android/index.mdx@@ -231,4 +231,4 @@ Tap the button and check your Traceway dashboard to verify the error appears wit|----------|----------------|------------------|| Android (API 21+) | Yes | No |-For Flutter apps that need cross-platform error tracking (and screen recording on iOS / Android / macOS), use the [Flutter SDK](/client/flutter?sdk=flutter) instead — it ships the same wire format so a single Traceway backend handles both.+For Flutter apps that need cross-platform error tracking (and screen recording on iOS / Android / macOS), use the [Flutter SDK](/client/flutter) instead — it ships the same wire format so a single Traceway backend handles both.diff --git a/docs/pages/client/flutter/index.mdx b/docs/pages/client/flutter/index.mdxindex 16d0e049..49678f67 100644--- a/docs/pages/client/flutter/index.mdx+++ b/docs/pages/client/flutter/index.mdx@@ -284,7 +284,7 @@ For Flutter web, use the JS SDK instead — see [Flutter Web](#flutter-web) belo## Flutter Web-This SDK does not support Flutter web. For web apps, use the [`@tracewayapp/frontend`](/client/js-sdk?sdk=js-generic) JS SDK which provides rrweb session replay and automatic fetch instrumentation.+This SDK does not support Flutter web. For web apps, use the [`@tracewayapp/frontend`](/client/js-sdk) JS SDK which provides rrweb session replay and automatic fetch instrumentation.**Add the CDN script to `web/index.html`:**@@ -308,4 +308,4 @@ npm install @tracewayapp/frontend</script>```-See the full [JS SDK documentation](/client/js-sdk?sdk=js-generic) for all options including session recording, error filtering, and distributed tracing.+See the full [JS SDK documentation](/client/js-sdk) for all options including session recording, error filtering, and distributed tracing.diff --git a/docs/pages/client/react-native/index.mdx b/docs/pages/client/react-native/index.mdxindex 39ce9cb7..cb57e9da 100644--- a/docs/pages/client/react-native/index.mdx+++ b/docs/pages/client/react-native/index.mdx@@ -26,7 +26,7 @@ export default function App() {That's it. Every uncaught throw, unhandled promise rejection, render-time exception, and `fetch` call is captured automatically. If you want to replace a crashed subtree with a custom fallback view, `TracewayErrorBoundary` is still exported for that purpose.-> **No screen recording.** Unlike the browser SDK ([`@tracewayapp/frontend`](/client/js-sdk?sdk=js-generic)), this package does not record the screen. The `rrweb` recorder is intentionally absent — nothing in the bundle reaches into a DOM that doesn't exist.+> **No screen recording.** Unlike the browser SDK ([`@tracewayapp/frontend`](/client/js-sdk)), this package does not record the screen. The `rrweb` recorder is intentionally absent — nothing in the bundle reaches into a DOM that doesn't exist.## Capture Errors Manually@@ -291,4 +291,4 @@ Tap the button and check your Traceway dashboard to verify the error appears wit| Expo (SDK 49+) | Yes — works in Expo Go | No || Web (via React Native Web) | Yes | No |-For native Android-only apps without React Native, use the [Android SDK](/client/android?sdk=android). For Flutter apps, use the [Flutter SDK](/client/flutter?sdk=flutter). For browser apps, use the [React SDK](/client/react?sdk=js-react) or [generic JS SDK](/client/js-sdk?sdk=js-generic).+For native Android-only apps without React Native, use the [Android SDK](/client/android). For Flutter apps, use the [Flutter SDK](/client/flutter). For browser apps, use the [React SDK](/client/react) or [generic JS SDK](/client/js-sdk).diff --git a/docs/styles/custom.css b/docs/styles/custom.cssindex 4035d0c5..d2d16fb0 100644--- a/docs/styles/custom.css+++ b/docs/styles/custom.css@@ -288,6 +288,27 @@ main hr,box-shadow: 0 0 0 3px color-mix(in oklab, var(--a1) 15%, transparent);}+/* Results panel: solid surface. Nextra's default is translucent + backdrop-blur,+ which lets page content bleed through and makes the results unreadable. */+.nextra-search ul.nextra-scrollbar {+ background-color: var(--ink-2) !important;+ -webkit-backdrop-filter: none !important;+ backdrop-filter: none !important;+ border-color: var(--hair-2) !important;+}++/* Matched query terms: Nextra colors these with the dark indigo primary, which+ is hard to read on the panel — lighten so the match stands out legibly. */+.nextra-search .nx-text-primary-600 {+ color: color-mix(in oklab, var(--a1) 55%, var(--fg-0)) !important;+ font-weight: 600;+}++/* Result excerpt: default gray-400 is too dim on the solid dark panel. */+.nextra-search .excerpt {+ color: var(--fg-1) !important;+}+/* =========================================================================Navbar alignment (pre-existing rules, preserved)========================================================================= */diff --git a/docs/theme.config.jsx b/docs/theme.config.jsxindex 013e4424..51631037 100644--- a/docs/theme.config.jsx+++ b/docs/theme.config.jsx@@ -14,6 +14,7 @@ const SDK_VISIBILITY = {nestjs: "js-nestjs",hono: "js-hono",react: "js-react",+ "react-native": "react-native",vue: "js-vue",svelte: "js-svelte",jquery: "js-jquery",@@ -23,6 +24,8 @@ const SDK_VISIBILITY = {cloudflare: "cloudflare",nextjs: "js-nextjs",symfony: "php-symfony",+ laravel: "php-laravel",+ django: "python-django",flutter: "flutter",android: "android",};@@ -80,10 +83,12 @@ export default {return <SdkSelector />;}- for (const [folder, requiredSdk] of Object.entries(SDK_VISIBILITY)) {- if (route && route.includes(`/${folder}`)) {- return <SdkGuard requiredSdk={requiredSdk}>{title}</SdkGuard>;- }+ const segment = route?.startsWith("/client")+ ? route.split("/").filter(Boolean)[1]+ : undefined;+ const requiredSdk = segment ? SDK_VISIBILITY[segment] : undefined;+ if (requiredSdk !== undefined) {+ return <SdkGuard requiredSdk={requiredSdk}>{title}</SdkGuard>;}return <>{title}</>;@@ -102,6 +107,9 @@ export default {function SdkGuard({ requiredSdk, children }) {const { sdk } = useSdk();+ if (!sdk) {+ return <HiddenItem />;+ }let visible;if (Array.isArray(requiredSdk)) {visible = requiredSdk.includes(sdk);