@gscdump/nuxt 0.21.3 → 0.22.4

package/README.md

@@ -31,13 +31,25 @@ pnpm add @gscdump/nuxt
 export default defineNuxtConfig({
   extends: ['@gscdump/nuxt'],
   runtimeConfig: {
-    analytics: {
-      mode: 'origin', // or 'consumer' / 'local'
+    public: {
+      analytics: {
+        apiBase: '', // same-origin by default; set to your analytics origin in consumer mode
+      },
     },
   },
 })
 ```
 
+Nuxt auto-imports the layer composables. If you prefer explicit imports, use
+per-composable entrypoints:
+
+```ts
+import { setGscAuth } from '@gscdump/nuxt/composables/useGscAuth'
+import { useGscRollup } from '@gscdump/nuxt/composables/useGscRollup'
+```
+
+The primary query interface is `useGscQuery` / `useGscAnalyzer`.
+
 ## Register an auth provider
 
 ```ts
@@ -60,11 +72,11 @@ export default defineNitroPlugin((nitro) => {
 
 | Need | Endpoint | Client composable |
 | --- | --- | --- |
-| Pre-aggregated widgets (top pages, daily totals) | `GET /api/sites/:siteId/rollup/:id` | `useGscRollup` / `useGscRollups` / `useGscRollupFanout` |
-| Raw rows filtered by dimension/range (`where(eq(page, ...))`) | `POST /api/sites/:siteId/rows` | `useGscRowQuery({ site, state })` |
-| Analyzer result (striking-distance, CTR anomaly, …) | `POST /api/sites/:siteId/analyze` | `useGscAnalyzer(siteId).analyze(...)` |
+| Pre-aggregated widgets (top pages, daily totals) | `GET /api/__gsc/sites/:siteId/rollup/:id` | `useGscRollup` / `useGscRollups` / `useGscRollupFanout` |
+| Raw rows filtered by dimension/range (`where(eq(page, ...))`) | `POST /api/__gsc/sites/:siteId/rows` | `useGscQuery({ siteId, params })` |
+| Analyzer result (striking-distance, CTR anomaly, …) | `POST /api/__gsc/sites/:siteId/analyze` | `useGscAnalyzer(siteId).analyze(...)` |
 
-Rule of thumb: reach for `/rows` + `useGscRowQuery` for detail pages that
+Rule of thumb: reach for `/rows` + `useGscQuery` for detail pages that
 need a freeform slice of the data. Only fall back to `/analyze` when the
 server runs an actual analyzer (anything in the registry); hitting it for
 plain row lookups routes through analyzer-gating logic you don't need.
@@ -78,39 +90,36 @@ the data — e.g. nuxtseo.com pro consuming gscdump.com. Two pieces:
    in `nuxt.config.ts` (or via `NUXT_PUBLIC_ANALYTICS_API_BASE`). Empty =
    same-origin (the default origin-mode shape).
 
-2. **Hand the layer a per-viewer api key**: register a client plugin that
-   trades the viewer's host session for an api key, then call
-   `setGscFetchHeaders({ 'x-api-key': key })`. The layer's `useGscFetch`
+2. **Hand the layer per-viewer auth**: register a client plugin that trades
+   the viewer's host session for an api key, then call
+   `setGscAuth({ apiKey: key })`. The layer's `useGscFetch`
    attaches the header to every `/api/__gsc/*` call automatically. Browser
    parquet reads use exact-object URLs minted by the source endpoint; runtime
    preflights can include this header, while DuckDB-WASM range reads are
    authorized by the token embedded in each URL.
 
-The `setupGscFetchAuth` helper collapses the boilerplate:
+Wire it from a `'pre'`-enforced client plugin so downstream layer plugins see
+the auth on first read. The layer's `setGscAuth` accepts a value, a `Ref`,
+or a getter — use a getter when credentials may refresh during the session:
 
 ```ts
 // plugins/00.gscdump-auth.client.ts
-export default setupGscFetchAuth({
-  credentialsEndpoint: '/api/me/gscdump-credentials',
-  // Optional: preload host-specific state. Runs inside runWithContext so
-  // composables work. Useful for useState-backed flags read by the layer's
-  // composables at construction time.
-  async onReady() {
-    const flag = useState<boolean | null>('app:browser-analyzer-enabled', () => null)
-    if (flag.value !== null)
-      return
-    const settings = await useGscFetch()<{ browserAnalyzerEnabled: boolean }>('/api/user/settings').catch(() => null)
-    flag.value = !!settings?.browserAnalyzerEnabled
+export default defineNuxtPlugin({
+  name: 'gscdump-auth',
+  enforce: 'pre',
+  async setup() {
+    const creds = ref<{ apiKey: string, browserAnalyzerEnabled?: boolean } | null>(null)
+    creds.value = await $fetch('/api/me/gscdump-credentials').catch(() => null)
+    setGscAuth(() => ({
+      apiKey: creds.value?.apiKey ?? null,
+      browserAnalyzerEnabled: !!creds.value?.browserAnalyzerEnabled,
+    }))
   },
 })
 ```
 
-The helper is `enforce: 'pre'` and dedupes via an inflight promise; Nuxt
-blocks subsequent plugins until headers land, removing the auth-header race
-where a `useGscQuery` mounts before credentials resolve.
-
-`credentialsEndpoint` returns `{ apiKey: string, ... }` by default. Override
-the field name with `tokenField` and the header name with `headerName`.
+`useGscQuery` mounts that race the credential fetch resolve once the
+`'pre'` plugin's `await` settles — Nuxt blocks subsequent plugins on it.
 
 Onboarding and lifecycle state stay outside this layer. A consumer app should
 use `@gscdump/sdk` from its host backend to register users/sites, read

package/app/components/GscDashboardPage.vue

@@ -14,10 +14,10 @@ const gapClass = computed(() => (
 </script>
 
 <template>
-  <div class="flex flex-col min-h-screen">
+  <div class="flex flex-col min-h-screen overflow-x-clip">
     <slot name="header" />
     <div
-      class="max-w-[1128px] px-4 sm:px-6 lg:px-9 pt-4 pb-10 flex flex-col flex-1 w-full"
+      class="max-w-[1128px] min-w-0 px-4 sm:px-6 lg:px-9 pt-4 pb-10 flex flex-col flex-1 w-full"
       :class="gapClass"
     >
       <slot />

package/app/components/GscHero.vue

@@ -204,10 +204,9 @@ const chartPrevData = computed(() => stats.value?.previous?.series ?? [])
       v-if="stats && chartData.length"
       class="rounded-lg border border-default bg-default p-4"
     >
-      <PerformanceChart
-        :data="chartData"
-        :previous-data="chartPrevData"
-        :show-comparison="compareMode !== 'none' && chartPrevData.length > 0"
+      <GscPerformanceChart
+        :value="chartData"
+        :prev-value="compareMode !== 'none' ? chartPrevData : null"
         :height="220"
       />
     </div>

package/app/components/GscLazyTopResult.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { useIntersectionObserver } from '@vueuse/core'
-import { useGscFetch } from '../utils/gsc-fetch'
+import { gscQueries } from '../queries/gsc'
+import { useGscRpc } from '../utils/gsc-rpc'
 
 const props = defineProps<{
   siteUrl: string
@@ -21,14 +22,15 @@ const { stop } = useIntersectionObserver(
       return
     loaded.value = true
     stop()
-    useGscFetch()<{ value: string | null }>(`/api/__gsc/sites/${encodeURIComponent(props.siteUrl)}/data/top-association`, {
-      query: {
+    const request = useGscRpc().query(
+      gscQueries.topAssociation(props.siteUrl, {
         type: props.type,
         identifier: props.identifier,
         startDate: props.startDate,
         endDate: props.endDate,
-      },
-    })
+      }),
+    ) as unknown as Promise<{ value: string | null }>
+    request
       .then(r => value.value = r.value)
       .catch(() => {})
   },

package/app/components/GscPerformanceChart.vue

@@ -297,11 +297,11 @@ const position = (d: DataRow) => d.position ?? 0
     <div v-if="loading" class="loading-skeleton">
       <div class="flex-1 flex items-end gap-1">
         <div v-for="i in 30" :key="i" class="flex-1 h-full flex">
-          <UiSkeleton type="bar" :index="i" />
+          <USkeleton class="w-full self-end" :style="{ height: `${28 + ((i * 17) % 56)}%` }" />
         </div>
       </div>
       <div class="flex justify-between mt-3">
-        <UiSkeleton v-for="i in 5" :key="i" class="h-3 w-12" />
+        <USkeleton v-for="i in 5" :key="i" class="h-3 w-12" />
       </div>
     </div>
 
@@ -444,11 +444,11 @@ const position = (d: DataRow) => d.position ?? 0
         <div class="loading-skeleton">
           <div class="flex-1 flex items-end gap-1">
             <div v-for="i in 30" :key="i" class="flex-1">
-              <UiSkeleton type="bar" :index="i" />
+              <USkeleton class="w-full self-end" :style="{ height: `${28 + ((i * 17) % 56)}%` }" />
             </div>
           </div>
           <div class="flex justify-between mt-3">
-            <UiSkeleton v-for="i in 5" :key="i" class="h-3 w-12" />
+            <USkeleton v-for="i in 5" :key="i" class="h-3 w-12" />
           </div>
         </div>
       </template>

package/app/components/GscSourceDebugPanel.vue

@@ -37,11 +37,12 @@ interface WhoamiResponse {
 }
 const whoami = ref<WhoamiResponse | null>(null)
 const whoamiLoading = ref(false)
+const analyticsClient = useGscAnalyticsClient()
 watchEffect(() => {
   if (!import.meta.client || resolvedSite.value || !open.value || whoami.value || whoamiLoading.value)
     return
   whoamiLoading.value = true
-  const request = useGscAnalyticsClient().whoami() as Promise<WhoamiResponse>
+  const request = analyticsClient.whoami() as Promise<WhoamiResponse>
   request
     .then((res) => { whoami.value = res })
     .catch(() => { /* surface via empty state, not a toast */ })

package/app/composables/_useGscBackfill.ts

@@ -2,8 +2,9 @@
 // on-demand backfill request, polls sync-progress, and invokes a refetch once
 // the requested range is synced.
 
-import { useGscFetch } from '../utils/gsc-fetch'
-import { useGscAnalyticsClient } from './useGscAnalyticsClient'
+import { invalidateNuxtQueries } from 'nuxt-use-query/query-cache'
+import { gscQueries } from '../queries/gsc'
+import { useGscRpc } from '../utils/gsc-rpc'
 
 interface BackfillRange {
   startDate: string
@@ -35,6 +36,7 @@ export function useGscBackfill(): GscBackfillState & {
   maybeTrigger: (meta: unknown, siteId: string, refetch: () => Promise<unknown> | unknown) => boolean
   reset: () => void
 } {
+  const rpc = useGscRpc()
   const pending = ref(false)
   const range = ref<BackfillRange | null>(null)
   const percent = ref(0)
@@ -48,7 +50,7 @@ export function useGscBackfill(): GscBackfillState & {
   }
 
   async function isRangeCovered(siteId: string, req: BackfillRange): Promise<boolean> {
-    const progress = await useGscFetch()<SyncProgressResponse>('/api/sync-progress').catch(() => null)
+    const progress = await rpc.query(gscQueries.syncProgress(), { silent: true }).catch(() => null) as SyncProgressResponse | null
     const site = progress?.sites?.find(s => s.id === siteId)
     if (!site?.oldestDateSynced || !site?.newestDateSynced)
       return false
@@ -63,7 +65,7 @@ export function useGscBackfill(): GscBackfillState & {
     error.value = null
     attemptedKeys.add(rangeKey(siteId, req))
 
-    await useGscAnalyticsClient().requestBackfill(siteId, req).catch((err) => {
+    await rpc.execute(gscQueries.backfill(siteId), { ...req }, { silent: true }).catch((err: unknown) => {
       error.value = (err as { data?: { message?: string }, message?: string })?.data?.message
         || (err as Error)?.message
         || 'Failed to queue backfill'
@@ -86,8 +88,14 @@ export function useGscBackfill(): GscBackfillState & {
     if (!covered)
       error.value = 'Backfill did not complete within the expected window. Try again later.'
 
-    if (covered)
+    if (covered) {
+      // Invalidate everything that depends on the newly synced range so
+      // consumers refetch instead of relying on the caller-passed refetch.
+      invalidateNuxtQueries(key => key.startsWith(`gsc:source-info:${siteId}`)
+        || key.startsWith(`gsc:analysis-sources:${siteId}`)
+        || key === 'gsc:sync-progress')
       await refetch()
+    }
     pending.value = false
     range.value = null
   }

package/app/composables/_useGscQueryDispatcher.ts

@@ -7,7 +7,8 @@
 
 import type { _useGscAuthInternal } from './useGscAuth'
 import type { GscQueryDecisionReason, GscQueryEngine } from './useGscQuery'
-import { useGscEngine } from './useGscEngine'
+
+const ENGINE_STATE_KEY = 'gscdump:engine'
 
 type InternalAuthState = ReturnType<typeof _useGscAuthInternal>['value']
 
@@ -26,14 +27,14 @@ export interface GscFallbackEvent {
 }
 
 export interface PickEngineOpts {
-  /** Per-call override. Wins over `useGscEngine()` + `runtimeConfig.public.analytics.defaultEngine`. */
+  /** Per-call override. Wins over the `gscdump:engine` useState + `runtimeConfig.public.analytics.defaultEngine`. */
   perCall?: GscQueryEngine
 }
 
 export interface GscQueryDispatcher {
   /**
    * Resolve the active engine into a concrete mode + reason. Consults the
-   * resolution chain: `opts.perCall` → `useGscEngine()` → runtimeConfig →
+   * resolution chain: `opts.perCall` → `gscdump:engine` useState → runtimeConfig →
    * `'auto'`. Then maps `auto` against `auth.browserAnalyzerEnabled`.
    */
   pickEngine: (auth: InternalAuthState, opts?: PickEngineOpts) => GscEngineDecision
@@ -110,7 +111,7 @@ export function createDefaultGscQueryDispatcher(
 }
 
 function resolveDefaultEngine(): GscQueryEngine {
-  const override = useGscEngine().value
+  const override = useState<GscQueryEngine | null>(ENGINE_STATE_KEY, () => null).value
   if (override)
     return override
   const cfg = useRuntimeConfig().public.analytics as { defaultEngine?: GscQueryEngine } | undefined

package/app/composables/_useGscResource.ts

@@ -1,36 +1,42 @@
-// Site-keyed async resource composable. Owns key-watch, stale-token discard,
-// status classification, refresh, and dispose for every read-only `/api/__gsc/*`
-// fetcher in the layer. Resource composables (useGscSitemaps,
-// useGscIndexingDiagnostics, …) are thin adapters that wire reactive keys to
-// `useGscAnalyticsClient().getX(...)` plus optional derived computeds.
-//
-// Stale-token (not AbortController) because `@gscdump/sdk`'s AnalyticsClient
-// doesn't accept a signal. Late-arriving promises from a superseded run are
-// dropped on `data`/`status` writes; the in-flight fetch still runs to
-// completion, which is acceptable for read-only GETs.
+// Site-keyed async resource composable. Owns key-watch, status classification,
+// refresh, and cache policy for every read-only `/api/__gsc/*` operation in
+// the layer. Resource composables stay thin adapters that wire reactive keys
+// to `gscQueries.*(...)` operations (preferred) — or to a `fetcher` for the
+// rollup composables that mix multiple operations + progress side-effects.
 
 import type { ComputedRef, Ref, WatchSource } from '@vue/runtime-core'
+import type { NuxtRpcQueryOperation } from 'nuxt-use-query/rpc'
 import type { GscErrorStatus } from '../utils/gsc-error'
+import { useNuxtRpcQuery } from 'nuxt-use-query/rpc'
 import { classifyGscError } from '../utils/gsc-error'
+import { useGscFetch } from '../utils/gsc-fetch'
 
 export type GscResourceStatus = 'idle' | 'pending' | 'success' | 'empty' | GscErrorStatus
 
 export interface UseGscResourceOptions<TArgs extends readonly unknown[], TData> {
   /** Reactive args passed to the fetcher. Resource stays idle while any required key is null/undefined. */
   keys: { [I in keyof TArgs]: MaybeRefOrGetter<TArgs[I] | null | undefined> }
-  /** Async fetcher invoked with the resolved keys. */
-  fetcher: (...args: TArgs) => Promise<TData | null>
+  /** RPC query operation invoked with the resolved keys. Preferred over `fetcher` — gets Zod validation + shared cache keying. */
+  operation?: (...args: TArgs) => NuxtRpcQueryOperation<any, any>
+  /** Composite async fetcher invoked with the resolved keys. Use only when an operation can't model the request (multi-call, progress side-effects). */
+  fetcher?: (...args: TArgs) => Promise<TData | null>
   /** Predicate for the `empty` status — defaults to checking `null`/`[]`/typical container fields. */
   isEmpty?: (data: TData) => boolean
   /** Extra reactive sources that should retrigger a fetch. */
   watchSources?: WatchSource[]
+  /** Optional namespace for the fetcher-mode cache key. Defaults to `gsc-resource`. Ignored when `operation` is provided (the operation owns its key). */
+  namespace?: string
+  /** Milliseconds before cached data is considered stale. Defaults to `nuxt-use-query`'s 0. */
+  staleTime?: number
+  /** Evict cached payload after the last consumer unmounts. Defaults to `nuxt-use-query`'s 5 min. */
+  gcTime?: number
 }
 
 export interface UseGscResourceReturn<TData> {
-  data: Ref<TData | null>
-  status: Ref<GscResourceStatus>
+  data: Readonly<Ref<TData | null>>
+  status: Readonly<Ref<GscResourceStatus>>
   loading: ComputedRef<boolean>
-  error: Ref<Error | null>
+  error: Readonly<Ref<Error | null>>
   refresh: () => Promise<void>
 }
 
@@ -53,14 +59,8 @@ function defaultIsEmpty(v: unknown): boolean {
 export function useGscResource<TArgs extends readonly unknown[], TData>(
   opts: UseGscResourceOptions<TArgs, TData>,
 ): UseGscResourceReturn<TData> {
-  const data = shallowRef<TData | null>(null)
-  const status = ref<GscResourceStatus>('idle')
-  const error = ref<Error | null>(null)
-  const loading = computed(() => status.value === 'pending')
-
-  let runToken = 0
-
-  function resolveKeys(): TArgs | null {
+  const namespace = opts.namespace ?? 'gsc-resource'
+  const resolvedArgs = computed<TArgs | null>(() => {
     const out: unknown[] = []
     for (const k of opts.keys) {
       const v = toValue(k)
@@ -69,46 +69,134 @@ export function useGscResource<TArgs extends readonly unknown[], TData>(
       out.push(v)
     }
     return out as unknown as TArgs
-  }
+  })
 
-  async function refresh(): Promise<void> {
-    const args = resolveKeys()
-    const token = ++runToken
-    if (!args) {
-      data.value = null
-      status.value = 'idle'
-      error.value = null
-      return
-    }
-    status.value = 'pending'
-    error.value = null
-    try {
-      const out = await opts.fetcher(...args)
-      if (token !== runToken)
-        return
-      data.value = out
-      const empty = out == null || (opts.isEmpty ?? defaultIsEmpty)(out)
-      status.value = empty ? 'empty' : 'success'
-    }
-    catch (e) {
-      if (token !== runToken)
+  const enabled = computed(() => resolvedArgs.value != null)
+  const gscFetch = useGscFetch()
+
+  // Operation branch: route through useNuxtRpcQuery so we inherit Zod
+  // response validation, RPC key serialization, and shared cache invalidation.
+  if (opts.operation) {
+    const operation = computed<NuxtRpcQueryOperation<any, any> | null>(() => {
+      const args = resolvedArgs.value
+      return args ? opts.operation!(...args) : null
+    })
+
+    // Idle placeholder when args aren't ready — useNuxtRpcQuery is always
+    // mounted, but the `enabled` gate prevents the request firing.
+    const fallbackOp = { key: `${namespace}:idle`, path: `${namespace}:idle`, response: { parse: (v: unknown) => v } as any }
+
+    const query = useNuxtRpcQuery<any>(
+      () => operation.value ?? fallbackOp,
+      {
+        enabled,
+        watch: opts.watchSources,
+        staleTime: opts.staleTime,
+        gcTime: opts.gcTime,
+        $fetch: gscFetch as any,
+      } as any,
+    )
+
+    const data = computed<TData | null>(() => {
+      if (!enabled.value)
+        return null
+      return (query.displayData.value ?? null) as TData | null
+    })
+
+    const error = computed<Error | null>(() => {
+      if (!enabled.value)
+        return null
+      const e = query.error.value
+      return e == null ? null : e instanceof Error ? e : new Error(String(e))
+    })
+
+    const status = computed<GscResourceStatus>(() => {
+      if (!enabled.value)
+        return 'idle'
+      if (query.status.value === 'pending')
+        return 'pending'
+      if (query.status.value === 'error') {
+        const classified = classifyGscError(error.value)
+        return classified.status
+      }
+      const out = data.value
+      if (query.status.value === 'success')
+        return out == null || (opts.isEmpty ?? defaultIsEmpty)(out) ? 'empty' : 'success'
+      return 'idle'
+    })
+
+    const loading = computed(() => status.value === 'pending')
+
+    async function refresh(): Promise<void> {
+      if (!enabled.value)
         return
-      const classified = classifyGscError(e)
-      error.value = e instanceof Error ? e : new Error(String(e))
-      status.value = classified.status
-      data.value = null
+      await query.refresh()
     }
+
+    return { data, status, loading, error, refresh }
   }
 
-  watch(
-    [...opts.keys.map(k => () => toValue(k)), ...(opts.watchSources ?? [])],
-    refresh,
-    { immediate: true },
-  )
+  // Fetcher branch: composables that can't be modelled as a single RPC
+  // operation (rollup fan-out, progress tracking) drop down to a raw
+  // useNuxtQuery + bound $fetch.
+  const queryKey = computed(() => {
+    const args = resolvedArgs.value
+    return args ? `${namespace}:${JSON.stringify(args)}` : `${namespace}:idle`
+  })
+
+  const fetchResource = (async () => {
+    const args = resolvedArgs.value
+    if (!args)
+      return null
+    if (opts.fetcher)
+      return await opts.fetcher(...args)
+    throw new Error('useGscResource: no operation or fetcher configured')
+  }) as unknown as typeof $fetch
+
+  const query = useNuxtQuery<TData | null, Error>(() => queryKey.value, {
+    key: () => queryKey.value,
+    enabled,
+    watch: opts.watchSources,
+    staleTime: opts.staleTime,
+    gcTime: opts.gcTime,
+    $fetch: fetchResource,
+  })
+
+  const data = computed<TData | null>(() => {
+    if (!enabled.value)
+      return null
+    return (query.displayData.value ?? null) as TData | null
+  })
+
+  const error = computed<Error | null>(() => {
+    if (!enabled.value)
+      return null
+    const e = query.error.value
+    return e == null ? null : e instanceof Error ? e : new Error(String(e))
+  })
 
-  onScopeDispose(() => {
-    runToken++
+  const status = computed<GscResourceStatus>(() => {
+    if (!enabled.value)
+      return 'idle'
+    if (query.status.value === 'pending')
+      return 'pending'
+    if (query.status.value === 'error') {
+      const classified = classifyGscError(error.value)
+      return classified.status
+    }
+    const out = data.value
+    if (query.status.value === 'success')
+      return out == null || (opts.isEmpty ?? defaultIsEmpty)(out) ? 'empty' : 'success'
+    return 'idle'
   })
 
+  const loading = computed(() => status.value === 'pending')
+
+  async function refresh(): Promise<void> {
+    if (!enabled.value)
+      return
+    await query.refresh()
+  }
+
   return { data, status, loading, error, refresh }
 }

package/app/composables/useGscAnalytics.ts

@@ -127,6 +127,7 @@ export function useGscBootProgress(): {
 }
 
 function createContext(): GscAnalyticsContext {
+  const client = useGscAnalyticsClient()
   const sites = ref<SiteListItem[] | null>(null)
   const sitesLoading = ref(false)
   const sitesError = ref<Error | null>(null)
@@ -135,7 +136,7 @@ function createContext(): GscAnalyticsContext {
   async function refreshSites(): Promise<void> {
     sitesLoading.value = true
     sitesError.value = null
-    sites.value = await useGscAnalyticsClient().listSites().catch((err) => {
+    sites.value = await client.listSites().catch((err: unknown) => {
       sitesError.value = err instanceof Error ? err : new Error(String(err))
       return null
     })
@@ -171,14 +172,22 @@ function createContext(): GscAnalyticsContext {
   // Lazy-load: defer refreshSites until something actually reads `sites`.
   // Eager kick-off used to race host plugins that set auth via `setGscAuth`;
   // first call would 401 and the rest of the session would silently degrade.
-  // Triggering on first read defers the request to a microtask after plugin
-  // setup, so auth state is in place.
+  // Triggering on first read still needs to wait until hydration is done:
+  // `refreshSites()` flips `sitesLoading` synchronously, and doing that during
+  // the client's first render makes the sidebar disagree with SSR markup.
   let kickedOff = false
   function maybeKickOff(): void {
     if (kickedOff || !import.meta.client)
       return
     kickedOff = true
-    refreshSites()
+    const start = (): void => {
+      void refreshSites()
+    }
+    const nuxtApp = useNuxtApp()
+    if (nuxtApp.isHydrating)
+      onNuxtReady(start)
+    else
+      queueMicrotask(start)
   }
   const lazySites = computed<SiteListItem[] | null>(() => {
     maybeKickOff()

package/app/composables/useGscAnalyticsSourceInfo.ts

@@ -9,8 +9,8 @@
 // entry per site/searchType/range via the shared site-resource seam, so they
 // collapse to one network read per session slice.
 
-import type { SourceCapabilities } from '@gscdump/analysis'
 import type { SourceInfoOptions } from '@gscdump/contracts'
+import type { SourceCapabilities } from '@gscdump/engine/source'
 import { acquireSharedEntry, useGscSharedSiteResource } from './_useGscSharedSiteResource'
 import { useGscAnalyticsClient } from './useGscAnalyticsClient'
 
@@ -69,12 +69,17 @@ function sourceInfoKey(siteId: string, options?: SourceInfoOptions): string {
   ])
 }
 
-function fetchInto(entry: SourceInfoEntry, siteId: string, options?: SourceInfoOptions): Promise<void> {
+function fetchInto(
+  entry: SourceInfoEntry,
+  siteId: string,
+  options?: SourceInfoOptions,
+  client = useGscAnalyticsClient(),
+): Promise<void> {
   if (entry.pending.value)
     return entry.pending.value
   entry.loading.value = true
   entry.error.value = null
-  const p = (useGscAnalyticsClient().getSourceInfo(siteId, options) as Promise<GscAnalyticsSourceInfo>)
+  const p = (client.getSourceInfo(siteId, options) as Promise<GscAnalyticsSourceInfo>)
     .then((data) => {
       entry.info.value = data
     })
@@ -112,6 +117,7 @@ export function useGscAnalyticsSourceInfo(
   siteId: MaybeRefOrGetter<string | null | undefined>,
   options: MaybeRefOrGetter<SourceInfoOptions | null | undefined> = null,
 ): GscAnalyticsSourceInfoState {
+  const client = useGscAnalyticsClient()
   const cacheKey = computed(() => {
     const id = toValue(siteId)
     return id ? sourceInfoKey(id, toValue(options) ?? undefined) : null
@@ -129,7 +135,7 @@ export function useGscAnalyticsSourceInfo(
       if (!id)
         return
       if (entry.info.value == null && entry.pending.value == null && entry.error.value == null)
-        void fetchInto(entry, id, toValue(options) ?? undefined)
+        void fetchInto(entry, id, toValue(options) ?? undefined, client)
     }, { immediate: true })
   }
 
@@ -143,7 +149,7 @@ export function useGscAnalyticsSourceInfo(
     if (!entry || !id)
       return
     entry.info.value = null
-    await fetchInto(entry, id, toValue(options) ?? undefined)
+    await fetchInto(entry, id, toValue(options) ?? undefined, client)
   }
 
   function supports(analyzerId: MaybeRefOrGetter<string>): ComputedRef<boolean> {