@gscdump/nuxt 0.19.0

package/app/composables/_useGscSharedSiteResource.ts

@@ -0,0 +1,136 @@
+// Per-site shared resource bag. Consolidates the bind/unbind/refcount pattern
+// that useGscAnalyzer and useGscAnalyticsSourceInfo each reinvented.
+//
+// Two entry points share one underlying bag (a module-scope WeakMap keyed by
+// the NuxtApp instance, so each app gets isolated state and SSR is safe):
+//   - useGscSharedSiteResource → composable, refcounted, scope-disposed.
+//   - acquireSharedEntry       → non-composable acquire for boot-time / non-
+//                                setup callers (e.g. analyzer createInstance).
+//
+// Refcounting via `onDispose` is opt-in:
+//   - omitted     → entry persists forever (cheap, share-only; e.g. /source-info)
+//   - provided    → refcounted; runs onDispose + drops the entry at refs=0
+//
+// Returns a `bound` computed that tracks the entry for the current siteId. The
+// caller wraps it in `computed(() => bound.value?.field ?? default)` to expose
+// reactive fields.
+
+import type { ComputedRef } from '@vue/runtime-core'
+import type { NuxtApp } from 'nuxt/app'
+
+interface CacheEntry<T> {
+  entry: T
+  refs: number
+}
+
+type NamespaceBag = Map<string, Map<string, CacheEntry<unknown>>>
+
+const bags = new WeakMap<NuxtApp, NamespaceBag>()
+
+function namespaceMap(namespace: string): Map<string, CacheEntry<unknown>> {
+  const app = useNuxtApp()
+  let bag = bags.get(app)
+  if (!bag) {
+    bag = new Map()
+    bags.set(app, bag)
+  }
+  let m = bag.get(namespace)
+  if (!m) {
+    m = new Map()
+    bag.set(namespace, m)
+  }
+  return m
+}
+
+/**
+ * Non-composable acquire — returns (and lazily creates) the shared entry for
+ * `(namespace, siteId)`. No refcount, no scope dispose. Intended for callers
+ * outside a Vue setup scope (analyzer boot IIFE, one-shot loaders) that still
+ * need to share state with the reactive `useGscSharedSiteResource` consumers.
+ */
+export function acquireSharedEntry<T>(
+  namespace: string,
+  siteId: string,
+  factory: (siteId: string) => T,
+): T {
+  const cache = namespaceMap(namespace) as Map<string, CacheEntry<T>>
+  let inst = cache.get(siteId)
+  if (!inst) {
+    inst = { entry: factory(siteId), refs: 0 }
+    cache.set(siteId, inst)
+  }
+  return inst.entry
+}
+
+export interface UseSharedSiteResourceOptions<T> {
+  /** Build the entry on first acquire for a site. */
+  factory: (siteId: string) => T
+  /** When set, refcount the entry and run on the last release (deletes from cache). */
+  onDispose?: (entry: T) => Promise<void> | void
+}
+
+export interface UseSharedSiteResourceReturn<T> {
+  bound: ComputedRef<T | null>
+  currentSiteId: Ref<string | null>
+}
+
+export function useGscSharedSiteResource<T>(
+  namespace: string,
+  siteId: MaybeRefOrGetter<string | null | undefined>,
+  opts: UseSharedSiteResourceOptions<T>,
+): UseSharedSiteResourceReturn<T> {
+  const cache = namespaceMap(namespace) as Map<string, CacheEntry<T>>
+
+  const boundRef = shallowRef<T | null>(null)
+  const currentSiteId = ref<string | null>(null)
+
+  function bind(id: string): void {
+    unbind()
+    let inst = cache.get(id)
+    if (!inst) {
+      inst = { entry: opts.factory(id), refs: 0 }
+      cache.set(id, inst)
+    }
+    inst.refs++
+    boundRef.value = inst.entry
+    currentSiteId.value = id
+  }
+
+  function unbind(): void {
+    const id = currentSiteId.value
+    if (!id) {
+      boundRef.value = null
+      return
+    }
+    const inst = cache.get(id)
+    boundRef.value = null
+    currentSiteId.value = null
+    if (!inst)
+      return
+    inst.refs--
+    if (inst.refs <= 0 && opts.onDispose) {
+      cache.delete(id)
+      void Promise.resolve(opts.onDispose(inst.entry)).catch(() => {})
+    }
+  }
+
+  watch(
+    () => toValue(siteId),
+    (id: string | null | undefined) => {
+      if (!id) {
+        unbind()
+        return
+      }
+      if (import.meta.client)
+        bind(id)
+    },
+    { immediate: true },
+  )
+
+  onScopeDispose(unbind)
+
+  return {
+    bound: computed(() => boundRef.value) as ComputedRef<T | null>,
+    currentSiteId,
+  }
+}

package/app/composables/useGscAnalytics.ts

@@ -0,0 +1,197 @@
+// Analytics context: sites list + shared boot-progress map + per-site analyzer
+// cache. Provided app-wide by the layer's plugin as `nuxtApp.$gscAnalytics`.
+// Pages reach in via narrower hooks (`useGscSites`, `useGscSite`,
+// `useGscAnalyzer`, `useGscBootProgress`) — no global mutable `currentSite`,
+// no leaked progress writers.
+
+import type { SiteListItem } from '@gscdump/contracts'
+import { useGscAnalyticsClient } from './useGscAnalyticsClient'
+
+export type { SiteListItem }
+
+export type ReadBackend = 'd1' | 'r2'
+
+export interface SiteRecord extends SiteListItem {
+  /** Canonical GSC site URL. Alias of `label` for back-compat. */
+  siteUrl: string
+  /**
+   * Which backend serves analysis for this site. Carried through from the
+   * sites endpoint; when omitted the value defaults to `'r2'` so legacy
+   * consumers keep working. Browser-attach eligibility is ultimately
+   * decided by the server's source provider via `browserAttachEligible`
+   * on `/api/__gsc/sites/:siteId/source-info`, not by this field.
+   */
+  readBackend: ReadBackend
+  syncStatus?: string | null
+}
+
+export type SiteLoadStage = 'idle' | 'wasm' | 'manifest' | 'attach' | 'ready' | 'error'
+
+export interface SiteLoadProgress {
+  siteId: string
+  stage: SiteLoadStage
+  /** Sub-units (parquet files, rollup JSONs) completed. */
+  filesAttached: number
+  /** Sub-units expected; 0 while unknown. */
+  filesTotal: number
+  startedAt: number
+  endedAt?: number
+  error?: string
+  source?: 'duckdb' | 'rollup' | string
+}
+
+export interface GscAnalyticsContext {
+  sites: Ref<SiteListItem[] | null>
+  sitesLoading: Readonly<Ref<boolean>>
+  sitesError: Readonly<Ref<Error | null>>
+  refreshSites: () => Promise<void>
+  progress: Readonly<Ref<Record<string, SiteLoadProgress>>>
+  /** Escape hatch for demos/tests — write raw progress entries. */
+  patchProgress: (siteId: string, patch: Partial<SiteLoadProgress>) => void
+  /** Escape hatch for demos/tests — clear progress map (all or one site). */
+  clearProgress: (siteId?: string) => void
+}
+
+// Factory exposed so the layer's Nuxt plugin can provide a single app-wide
+// context via `provide: { gscAnalytics: createGscAnalyticsContext() }`.
+export function createGscAnalyticsContext(): GscAnalyticsContext {
+  return createContext()
+}
+
+/** Resolve the shared context. The layer's plugin guarantees this is provided. */
+export function useGscAnalyticsContext(): GscAnalyticsContext {
+  return useNuxtApp().$gscAnalytics
+}
+
+/** Read-only sites list + refresh. */
+export function useGscSites(): {
+  sites: Ref<SiteListItem[] | null>
+  loading: Readonly<Ref<boolean>>
+  error: Readonly<Ref<Error | null>>
+  refresh: () => Promise<void>
+} {
+  const { sites, sitesLoading, sitesError, refreshSites } = useGscAnalyticsContext()
+  return { sites, loading: sitesLoading, error: sitesError, refresh: refreshSites }
+}
+
+/** Derived site record for a given id. Non-mutating; returns `null` until the list resolves. */
+export function useGscSite(siteId: MaybeRefOrGetter<string | null | undefined>): Ref<SiteRecord | null> {
+  const { sites } = useGscAnalyticsContext()
+  return computed(() => {
+    const id = toValue(siteId)
+    if (!id)
+      return null
+    const found = sites.value?.find((s: SiteListItem) => s.id === id)
+    if (found)
+      return toSiteRecord(found)
+    // List not yet loaded — stamp a minimal record so downstream queries can
+    // dispatch against the id. Gets upgraded when sites resolves.
+    return {
+      id,
+      label: id,
+      hostname: id,
+      propertyType: 'url-prefix',
+      siteUrl: id,
+      readBackend: 'r2',
+    }
+  })
+}
+
+function toSiteRecord(s: SiteListItem): SiteRecord {
+  return {
+    ...s,
+    siteUrl: s.label,
+    readBackend: s.readBackend ?? 'r2',
+  }
+}
+
+/** Read-only boot-progress map for UI indicators. */
+export function useGscBootProgress(): {
+  progress: Readonly<Ref<Record<string, SiteLoadProgress>>>
+  entries: ComputedRef<SiteLoadProgress[]>
+  allReady: ComputedRef<boolean>
+  anyActive: ComputedRef<boolean>
+} {
+  const { progress } = useGscAnalyticsContext()
+  const entries = computed<SiteLoadProgress[]>(() => {
+    const all = Object.values(progress.value) as SiteLoadProgress[]
+    return all.sort((a, b) => a.startedAt - b.startedAt)
+  })
+  const allReady = computed(() =>
+    entries.value.length > 0 && entries.value.every((s: SiteLoadProgress) => s.stage === 'ready'),
+  )
+  const anyActive = computed(() =>
+    entries.value.some((s: SiteLoadProgress) => s.stage !== 'ready' && s.stage !== 'idle' && s.stage !== 'error'),
+  )
+  return { progress, entries, allReady, anyActive }
+}
+
+function createContext(): GscAnalyticsContext {
+  const sites = ref<SiteListItem[] | null>(null)
+  const sitesLoading = ref(false)
+  const sitesError = ref<Error | null>(null)
+  const progress = ref<Record<string, SiteLoadProgress>>({})
+
+  async function refreshSites(): Promise<void> {
+    sitesLoading.value = true
+    sitesError.value = null
+    sites.value = await useGscAnalyticsClient().listSites().catch((err) => {
+      sitesError.value = err instanceof Error ? err : new Error(String(err))
+      return null
+    })
+    sitesLoading.value = false
+  }
+
+  function patchProgress(siteId: string, patch: Partial<SiteLoadProgress>): void {
+    const prev = progress.value[siteId]
+    progress.value = {
+      ...progress.value,
+      [siteId]: {
+        siteId,
+        stage: 'idle',
+        filesAttached: 0,
+        filesTotal: 0,
+        startedAt: prev?.startedAt ?? Date.now(),
+        ...prev,
+        ...patch,
+      },
+    }
+  }
+
+  function clearProgress(siteId?: string): void {
+    if (!siteId) {
+      progress.value = {}
+      return
+    }
+    const next = { ...progress.value }
+    delete next[siteId]
+    progress.value = next
+  }
+
+  // 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.
+  let kickedOff = false
+  function maybeKickOff(): void {
+    if (kickedOff || !import.meta.client)
+      return
+    kickedOff = true
+    refreshSites()
+  }
+  const lazySites = computed<SiteListItem[] | null>(() => {
+    maybeKickOff()
+    return sites.value
+  })
+
+  return {
+    sites: lazySites as Readonly<Ref<SiteListItem[] | null>> as unknown as Ref<SiteListItem[] | null>,
+    sitesLoading: sitesLoading as Readonly<Ref<boolean>>,
+    sitesError: sitesError as Readonly<Ref<Error | null>>,
+    refreshSites,
+    progress: progress as Readonly<Ref<Record<string, SiteLoadProgress>>>,
+    patchProgress,
+    clearProgress,
+  }
+}

package/app/composables/useGscAnalyticsClient.ts

@@ -0,0 +1,9 @@
+// Reader for the layer's `AnalyticsClient`. Built once per NuxtApp by the
+// layer plugin and provided as `$gscAnalyticsClient`. Hosts override by
+// providing their own from a later plugin (e.g. to swap the SDK transport).
+
+import type { AnalyticsClient } from '@gscdump/sdk'
+
+export function useGscAnalyticsClient(): AnalyticsClient {
+  return useNuxtApp().$gscAnalyticsClient as AnalyticsClient
+}

package/app/composables/useGscAnalyticsConfig.ts

@@ -0,0 +1,8 @@
+// Typed reader for `runtimeConfig.public.analytics`. Single accessor so leaf
+// composables stop re-typing the cast and silently drift when keys are added.
+
+import type { GscAnalyticsRuntimeConfig } from '../../types'
+
+export function useGscAnalyticsConfig(): GscAnalyticsRuntimeConfig {
+  return useRuntimeConfig().public.analytics as unknown as GscAnalyticsRuntimeConfig
+}

package/app/composables/useGscAnalyticsSourceInfo.ts

@@ -0,0 +1,143 @@
+// Per-site reactive probe of what the server-resolved AnalysisQuerySource
+// can do. The layer exposes source shape (kind + analyzer set); tier logic
+// lives in the host.
+//
+// Use this to render locked/ghost UI upfront without issuing a doomed
+// analyze() call for each panel.
+//
+// The reactive composable and the non-reactive `loadSourceInfoFor` (used by
+// `useGscAnalyzer.createInstance`) share one entry per site via the shared
+// site-resource seam, so they collapse to one network read per session.
+
+import type { SourceCapabilities } from '@gscdump/analysis'
+import { acquireSharedEntry, useGscSharedSiteResource } from './_useGscSharedSiteResource'
+import { useGscAnalyticsClient } from './useGscAnalyticsClient'
+
+export interface GscAnalyticsSourceInfo {
+  /** Source implementation name — e.g. "gsc-api", "engine", "browser". */
+  name: string
+  /** `row` = GSC API / in-memory; `sql` = DuckDB/SQLite-backed. */
+  kind: 'row' | 'sql'
+  capabilities: SourceCapabilities
+  /** Analyzer ids runnable against this source, from the default registry. */
+  supportedAnalyzerIds: string[]
+  /** Host declared attach hint — client should boot DuckDB-WASM and attach parquets. */
+  browserAttachEligible: boolean
+  /**
+   * Host-controlled identity attrs echoed back for debug/display (e.g.
+   * `{ tier: 'free' | 'pro' }`). Layer treats as opaque — never use these
+   * for gating on the client, the source provider is the gate.
+   */
+  identityAttrs?: Record<string, unknown> | null
+}
+
+interface GscAnalyticsSourceInfoState {
+  info: Ref<GscAnalyticsSourceInfo | null>
+  loading: Ref<boolean>
+  error: Ref<Error | null>
+  refresh: () => Promise<void>
+  /** Convenience predicate for panel gating: true when the analyzer id is in `supportedAnalyzerIds`. */
+  supports: (analyzerId: MaybeRefOrGetter<string>) => ComputedRef<boolean>
+}
+
+interface SourceInfoEntry {
+  info: Ref<GscAnalyticsSourceInfo | null>
+  loading: Ref<boolean>
+  error: Ref<Error | null>
+  pending: Ref<Promise<void> | null>
+}
+
+const SOURCE_INFO_NAMESPACE = 'source-info'
+
+function createEntry(): SourceInfoEntry {
+  return {
+    info: ref<GscAnalyticsSourceInfo | null>(null),
+    loading: ref(false),
+    error: ref<Error | null>(null),
+    pending: shallowRef<Promise<void> | null>(null),
+  }
+}
+
+function fetchInto(entry: SourceInfoEntry, siteId: string): Promise<void> {
+  if (entry.pending.value)
+    return entry.pending.value
+  entry.loading.value = true
+  entry.error.value = null
+  const p = (useGscAnalyticsClient().getSourceInfo(siteId) as Promise<GscAnalyticsSourceInfo>)
+    .then((data) => {
+      entry.info.value = data
+    })
+    .catch((err: unknown) => {
+      entry.error.value = err instanceof Error ? err : new Error(String(err))
+    })
+    .finally(() => {
+      entry.loading.value = false
+      entry.pending.value = null
+    })
+  entry.pending.value = p
+  return p
+}
+
+/**
+ * Non-reactive source-info loader for callers outside a Vue scope (e.g. the
+ * analyzer's boot IIFE in `useGscAnalyzer.createInstance`). Shares the same
+ * per-site cache `useGscAnalyticsSourceInfo` consumes via the shared
+ * site-resource seam, so gating UI and the analyzer mode probe collapse to
+ * one network read per site per session.
+ */
+export async function loadSourceInfoFor(siteId: string): Promise<GscAnalyticsSourceInfo> {
+  const entry = acquireSharedEntry(SOURCE_INFO_NAMESPACE, siteId, createEntry)
+  if (entry.info.value)
+    return entry.info.value
+  await fetchInto(entry, siteId)
+  if (entry.error.value)
+    throw entry.error.value
+  if (!entry.info.value)
+    throw new Error(`loadSourceInfoFor(${siteId}): no info after fetch`)
+  return entry.info.value
+}
+
+export function useGscAnalyticsSourceInfo(
+  siteId: MaybeRefOrGetter<string | null | undefined>,
+): GscAnalyticsSourceInfoState {
+  const { bound } = useGscSharedSiteResource<SourceInfoEntry>(SOURCE_INFO_NAMESPACE, siteId, {
+    factory: () => createEntry(),
+    // No onDispose: source-info is cheap and persistent across the session.
+  })
+
+  if (import.meta.client) {
+    watch(bound, (entry: SourceInfoEntry | null) => {
+      if (!entry)
+        return
+      const id = toValue(siteId)
+      if (!id)
+        return
+      if (entry.info.value == null && entry.pending.value == null && entry.error.value == null)
+        void fetchInto(entry, id)
+    }, { immediate: true })
+  }
+
+  const info = computed(() => bound.value?.info.value ?? null) as unknown as Ref<GscAnalyticsSourceInfo | null>
+  const loading = computed(() => bound.value?.loading.value ?? false) as unknown as Ref<boolean>
+  const error = computed(() => bound.value?.error.value ?? null) as unknown as Ref<Error | null>
+
+  async function refresh(): Promise<void> {
+    const entry = bound.value
+    const id = toValue(siteId)
+    if (!entry || !id)
+      return
+    entry.info.value = null
+    await fetchInto(entry, id)
+  }
+
+  function supports(analyzerId: MaybeRefOrGetter<string>): ComputedRef<boolean> {
+    return computed(() => {
+      const list = bound.value?.info.value?.supportedAnalyzerIds
+      if (!list)
+        return false
+      return list.includes(toValue(analyzerId))
+    })
+  }
+
+  return { info, loading, error, refresh, supports }
+}