@gscdump/nuxt 0.21.3 → 0.22.4

package/app/utils/duckdb-wasm.ts

@@ -0,0 +1,166 @@
+// Shared browser-DuckDB-WASM helpers used by per-site analyzers and the
+// home-page multi-site fanout. Both consumers boot the same WASM bundle and
+// run the same in-memory parquet attach path; OPFS attach lives in the caller
+// because the two lifecycle models (refcounted long-lived vs ephemeral
+// per-run) need different handle ownership.
+
+import type { AsyncDuckDB, AsyncDuckDBConnection } from '@duckdb/duckdb-wasm'
+import type { DuckDBWasmBootResult, OpfsAttachedHandle } from '@gscdump/engine-duckdb-wasm'
+
+/**
+ * Boot DuckDB-WASM using the layer's configured bundle base. The dynamic
+ * `import('@gscdump/engine-duckdb-wasm')` keeps the WASM bundle out of the
+ * SSR build; callers should also gate the call behind `import.meta.client`.
+ *
+ * The `filesystem` config disables HEAD-request preflight and forces full
+ * HTTP reads — Cloudflare Workers strips `Content-Length` on streamed
+ * responses, which makes DuckDB's default range-request path 404.
+ */
+export async function bootGscDuckDBWasm(bundleBase?: string): Promise<DuckDBWasmBootResult> {
+  const { bootDuckDBWasm } = await import('@gscdump/engine-duckdb-wasm')
+  return bootDuckDBWasm({
+    ...(bundleBase
+      ? {
+          bundles: {
+            mvp: { mainModule: `${bundleBase}/duckdb-mvp.wasm`, mainWorker: `${bundleBase}/duckdb-browser-mvp.worker.js` },
+            eh: { mainModule: `${bundleBase}/duckdb-eh.wasm`, mainWorker: `${bundleBase}/duckdb-browser-eh.worker.js` },
+          },
+        }
+      : {}),
+    config: { filesystem: { reliableHeadRequests: false, allowFullHTTPReads: true } },
+  })
+}
+
+/**
+ * Process-wide shared boot. The ~800ms WASM boot is the dominant cost on the
+ * warm path (OPFS cache-hit means downloads are skipped); paying it once per
+ * session instead of per refresh turns date-range changes / search-type
+ * swaps into near-instant updates.
+ *
+ * Callers that want their own throwaway instance can keep using
+ * {@link bootGscDuckDBWasm}; those that want session-wide reuse — the home
+ * page fanout and the per-site analyzer — go through this.
+ *
+ * Browser-only. The `bundleBase` is captured from the first call; subsequent
+ * calls reuse the promise and ignore the argument (it's a deployment-wide
+ * constant in practice).
+ */
+let sharedBootPromise: Promise<DuckDBWasmBootResult> | null = null
+let sharedBootColdMs: number | undefined
+export function sharedGscDuckDBWasm(bundleBase?: string): Promise<DuckDBWasmBootResult> {
+  if (!sharedBootPromise) {
+    if (typeof performance !== 'undefined')
+      performance.mark('gsc:duckdb:boot:start')
+    const start = typeof performance !== 'undefined' ? performance.now() : 0
+    sharedBootPromise = bootGscDuckDBWasm(bundleBase).then((b) => {
+      if (typeof performance !== 'undefined') {
+        sharedBootColdMs = performance.now() - start
+        performance.mark('gsc:duckdb:boot:end')
+      }
+      return b
+    })
+  }
+  else if (typeof performance !== 'undefined') {
+    performance.mark('gsc:duckdb:boot:reuse')
+  }
+  return sharedBootPromise
+}
+
+/** Diagnostics: ms paid for the one-time cold boot, or undefined if not yet booted. */
+export function sharedGscDuckDBWasmColdMs(): number | undefined {
+  return sharedBootColdMs
+}
+
+/**
+ * Fetch every URL into a `Uint8Array` in parallel. `onFileFetched` ticks
+ * once per successful download. Separate from `registerParquetView` so
+ * callers can run fetches outside any connection mutex.
+ */
+export async function fetchParquetBuffers(
+  urls: readonly string[],
+  onFileFetched?: () => void,
+): Promise<Uint8Array[]> {
+  return Promise.all(urls.map(async (url) => {
+    const r = await fetch(url, { credentials: 'omit' })
+    if (!r.ok)
+      throw new Error(`GET ${url} failed: ${r.status}`)
+    const buf = new Uint8Array(await r.arrayBuffer())
+    onFileFetched?.()
+    return buf
+  }))
+}
+
+/**
+ * Register pre-fetched parquet buffers as virtual files, then build a single
+ * view that unions them. `CAST(date AS DATE)` canonicalises the legacy-VARCHAR
+ * / new-DATE encodings. File-name uniqueness is the caller's job; pass a
+ * `viewName` that already encodes any site/table salt so concurrent attaches
+ * across sites don't collide on the DuckDB virtual filesystem. Call under the
+ * DuckDB-WASM single-connection mutex.
+ */
+export async function registerParquetView(opts: {
+  db: AsyncDuckDB
+  conn: AsyncDuckDBConnection
+  viewName: string
+  buffers: readonly Uint8Array[]
+}): Promise<void> {
+  const { db, conn, viewName, buffers } = opts
+  const fileNames = buffers.map((_, i) => `${viewName}_${i}.parquet`)
+  for (let i = 0; i < buffers.length; i++)
+    await db.registerFileBuffer(fileNames[i]!, buffers[i]!)
+  const fileList = fileNames.map(n => `'${n.replace(/'/g, '\'\'')}'`).join(',')
+  await conn.query(`CREATE OR REPLACE VIEW ${viewName} AS SELECT * REPLACE (CAST(date AS DATE) AS date) FROM read_parquet([${fileList}], union_by_name = true)`)
+}
+
+/**
+ * Attach a parquet file set into DuckDB-WASM, preferring the OPFS-backed
+ * path (cache-hit skips download) and falling back to in-memory buffers when
+ * OPFS is opted out, unavailable, or quota-exhausted.
+ *
+ * Returns the OPFS handle when the OPFS path succeeded — caller must keep
+ * the handle alive and `detach()` on cleanup. Returns `null` when the
+ * fallback path was used; nothing to detach. `onFileProgress` ticks once per
+ * downloaded file in either path so the caller can drive a progress UI.
+ *
+ * `withDb` wraps the DDL/file-register calls when the caller serialises
+ * against other DuckDB activity (e.g. a shared connection); pass `undefined`
+ * when the caller already owns a private connection.
+ */
+export async function attachParquetWithFallback(args: {
+  db: AsyncDuckDB
+  conn: AsyncDuckDBConnection
+  viewName: string
+  files: readonly { url: string, bytes: number, contentHash: string }[]
+  version: string
+  useOpfsCache: boolean
+  fetchConcurrency?: number
+  onFileProgress?: () => void
+  withDb?: <T>(fn: () => Promise<T>) => Promise<T>
+}): Promise<OpfsAttachedHandle | null> {
+  const { db, conn, viewName, files, version, useOpfsCache, onFileProgress } = args
+  const lock = args.withDb ?? (<T>(fn: () => Promise<T>) => fn())
+  const fetchConcurrency = args.fetchConcurrency ?? Math.min(files.length, 4)
+
+  if (useOpfsCache) {
+    const { attachOpfsParquetTables } = await import('@gscdump/engine-duckdb-wasm')
+    const handle = await lock(() => attachOpfsParquetTables({
+      db,
+      conn,
+      tables: [{
+        table: viewName,
+        files: files.map(f => ({ url: f.url, bytes: f.bytes, contentHash: f.contentHash })),
+      }],
+      version,
+      fetchConcurrency,
+      onFileProgress,
+    }))
+    if (!handle.degradedTables.includes(viewName))
+      return handle
+    // OPFS quota / failure — fall through to buffer path. Caller's progress
+    // counter restarts; both paths report one tick per fetched file.
+  }
+
+  const buffers = await fetchParquetBuffers(files.map(f => f.url), onFileProgress)
+  await lock(() => registerParquetView({ db, conn, viewName, buffers }))
+  return null
+}

package/app/utils/gsc-rpc.ts

@@ -0,0 +1,18 @@
+import type { NuxtRpcErrorEvent, UseNuxtRpcOptions } from 'nuxt-use-query/rpc'
+import { toHumanNuxtRpcError, useNuxtRpc } from 'nuxt-use-query/rpc'
+import { useGscFetch } from './gsc-fetch'
+
+// Layer-shared RPC executor. Routes through `useGscFetch()` so auth headers and
+// the configured `apiBase` (cross-origin gscdump.com deployments) are honoured.
+// Defaults `onError` to log a humanised message via `toHumanNuxtRpcError`; the
+// toast is already emitted by `useGscFetch`'s `onResponseError`, so this is
+// non-duplicate diagnostic output that hosts can override.
+export function useGscRpc(options: UseNuxtRpcOptions = {}): ReturnType<typeof useNuxtRpc> {
+  return useNuxtRpc({
+    ...options,
+    fetch: options.fetch ?? (useGscFetch() as UseNuxtRpcOptions['fetch']),
+    onError: options.onError ?? ((event: NuxtRpcErrorEvent) => {
+      console.warn(`[gsc-rpc] ${event.operation.method} ${event.operation.path}: ${toHumanNuxtRpcError(event.error)}`)
+    }),
+  })
+}

package/module.ts

@@ -67,7 +67,7 @@ export default defineNuxtModule<ModuleOptions>({
       })
     }
 
-    // Strip underscore-prefixed composables from the consumer auto-import surface.
+    // Strip internal composables from the consumer auto-import surface.
     // `app/composables/_useFoo.ts` stays usable inside the layer via explicit
     // relative imports, but never appears as a global auto-import in host apps.
     nuxt.hook('imports:extend', (imports) => {

package/nuxt.config.ts

@@ -14,12 +14,37 @@ import { fileURLToPath } from 'node:url'
 export default defineNuxtConfig({
   // Register the layer's module so hooks + runtime config land on host apps
   // without them having to wire each module individually.
+  //
+  // `nuxt-use-query` provides `useNuxtQuery` / `useQueryCache` — TanStack-Query-
+  // shaped wrapper over `useFetch`. Composables in this layer fetch through
+  // it for SWR + dedup.
   modules: [
     fileURLToPath(new URL('./module.ts', import.meta.url)),
     '@nuxt/ui',
     '@vueuse/nuxt',
+    'nuxt-use-query',
   ],
 
+  // Enforce shared/contracts + app/queries pattern at build time so host apps
+  // can't drift back to hardcoded `/api/*` literals in components / composables.
+  // Hosts can opt out per-site by overriding `nuxtUseQuery.contracts.enabled`.
+  nuxtUseQuery: {
+    contracts: {
+      enabled: true,
+      // `@gscdump/contracts` is the shared package alias for hosted-API wire
+      // shapes — query files must import from there (or a host
+      // `shared/contracts/*`).
+      apiPrefixes: ['/api/__gsc', '/api/sync-progress'],
+      queryDirs: ['app/queries', 'layers/*/app/queries'],
+      contractDirs: ['shared/contracts', 'layers/*/shared/contracts', '@gscdump/contracts'],
+      serverApiDirs: ['server/api', 'layers/*/server/api'],
+      requireServerContracts: false,
+      // The config file declares these prefixes so the scanner must skip it.
+      // (overrides the default ignore set — keep the defaults alongside it.)
+      ignore: ['.git', '.nuxt', '.output', 'coverage', 'dist', 'node_modules', 'nuxt.config.ts'],
+    },
+  },
+
   css: [
     fileURLToPath(new URL('./app/assets/css/main.css', import.meta.url)),
   ],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/nuxt",
   "type": "module",
-  "version": "0.21.3",
+  "version": "0.22.4",
   "description": "Nuxt layer: GSC analytics UI + DuckDB-WASM integration. Frontend-only; server primitives live in @gscdump/analysis, @gscdump/engine-sqlite, @gscdump/cloudflare, and host apps.",
   "author": {
     "name": "Harlan Wilton",
@@ -30,6 +30,136 @@
       "types": "./module.ts",
       "import": "./module.ts",
       "default": "./module.ts"
+    },
+    "./queries/gsc": {
+      "types": "./app/queries/gsc.ts",
+      "import": "./app/queries/gsc.ts",
+      "default": "./app/queries/gsc.ts"
+    },
+    "./composables/useGscAnalytics": {
+      "types": "./app/composables/useGscAnalytics.ts",
+      "import": "./app/composables/useGscAnalytics.ts",
+      "default": "./app/composables/useGscAnalytics.ts"
+    },
+    "./composables/useGscAnalyticsClient": {
+      "types": "./app/composables/useGscAnalyticsClient.ts",
+      "import": "./app/composables/useGscAnalyticsClient.ts",
+      "default": "./app/composables/useGscAnalyticsClient.ts"
+    },
+    "./composables/useGscAnalyticsConfig": {
+      "types": "./app/composables/useGscAnalyticsConfig.ts",
+      "import": "./app/composables/useGscAnalyticsConfig.ts",
+      "default": "./app/composables/useGscAnalyticsConfig.ts"
+    },
+    "./composables/useGscAnalyticsSourceInfo": {
+      "types": "./app/composables/useGscAnalyticsSourceInfo.ts",
+      "import": "./app/composables/useGscAnalyticsSourceInfo.ts",
+      "default": "./app/composables/useGscAnalyticsSourceInfo.ts"
+    },
+    "./composables/useGscAnalyzer": {
+      "types": "./app/composables/useGscAnalyzer.ts",
+      "import": "./app/composables/useGscAnalyzer.ts",
+      "default": "./app/composables/useGscAnalyzer.ts"
+    },
+    "./composables/useGscAnalyzerBatch": {
+      "types": "./app/composables/useGscAnalyzerBatch.ts",
+      "import": "./app/composables/useGscAnalyzerBatch.ts",
+      "default": "./app/composables/useGscAnalyzerBatch.ts"
+    },
+    "./composables/useGscAnalyzerDefs": {
+      "types": "./app/composables/useGscAnalyzerDefs.ts",
+      "import": "./app/composables/useGscAnalyzerDefs.ts",
+      "default": "./app/composables/useGscAnalyzerDefs.ts"
+    },
+    "./composables/useGscAuth": {
+      "types": "./app/composables/useGscAuth.ts",
+      "import": "./app/composables/useGscAuth.ts",
+      "default": "./app/composables/useGscAuth.ts"
+    },
+    "./composables/useGscConsoleUrl": {
+      "types": "./app/composables/useGscConsoleUrl.ts",
+      "import": "./app/composables/useGscConsoleUrl.ts",
+      "default": "./app/composables/useGscConsoleUrl.ts"
+    },
+    "./composables/useGscCountries": {
+      "types": "./app/composables/useGscCountries.ts",
+      "import": "./app/composables/useGscCountries.ts",
+      "default": "./app/composables/useGscCountries.ts"
+    },
+    "./composables/useGscCurrentSite": {
+      "types": "./app/composables/useGscCurrentSite.ts",
+      "import": "./app/composables/useGscCurrentSite.ts",
+      "default": "./app/composables/useGscCurrentSite.ts"
+    },
+    "./composables/useGscInspectionHistory": {
+      "types": "./app/composables/useGscInspectionHistory.ts",
+      "import": "./app/composables/useGscInspectionHistory.ts",
+      "default": "./app/composables/useGscInspectionHistory.ts"
+    },
+    "./composables/useGscInspections": {
+      "types": "./app/composables/useGscInspections.ts",
+      "import": "./app/composables/useGscInspections.ts",
+      "default": "./app/composables/useGscInspections.ts"
+    },
+    "./composables/useGscPanelContext": {
+      "types": "./app/composables/useGscPanelContext.ts",
+      "import": "./app/composables/useGscPanelContext.ts",
+      "default": "./app/composables/useGscPanelContext.ts"
+    },
+    "./composables/useGscPeriod": {
+      "types": "./app/composables/useGscPeriod.ts",
+      "import": "./app/composables/useGscPeriod.ts",
+      "default": "./app/composables/useGscPeriod.ts"
+    },
+    "./composables/useGscQuery": {
+      "types": "./app/composables/useGscQuery.ts",
+      "import": "./app/composables/useGscQuery.ts",
+      "default": "./app/composables/useGscQuery.ts"
+    },
+    "./composables/useGscQueryDispatcher": {
+      "types": "./app/composables/useGscQueryDispatcher.ts",
+      "import": "./app/composables/useGscQueryDispatcher.ts",
+      "default": "./app/composables/useGscQueryDispatcher.ts"
+    },
+    "./composables/useGscRequestIndexingInspect": {
+      "types": "./app/composables/useGscRequestIndexingInspect.ts",
+      "import": "./app/composables/useGscRequestIndexingInspect.ts",
+      "default": "./app/composables/useGscRequestIndexingInspect.ts"
+    },
+    "./composables/useGscResource": {
+      "types": "./app/composables/useGscResource.ts",
+      "import": "./app/composables/useGscResource.ts",
+      "default": "./app/composables/useGscResource.ts"
+    },
+    "./composables/useGscRollup": {
+      "types": "./app/composables/useGscRollup.ts",
+      "import": "./app/composables/useGscRollup.ts",
+      "default": "./app/composables/useGscRollup.ts"
+    },
+    "./composables/useGscSearchAppearance": {
+      "types": "./app/composables/useGscSearchAppearance.ts",
+      "import": "./app/composables/useGscSearchAppearance.ts",
+      "default": "./app/composables/useGscSearchAppearance.ts"
+    },
+    "./composables/useGscSiteAnalyzer": {
+      "types": "./app/composables/useGscSiteAnalyzer.ts",
+      "import": "./app/composables/useGscSiteAnalyzer.ts",
+      "default": "./app/composables/useGscSiteAnalyzer.ts"
+    },
+    "./composables/useGscSitemapHistory": {
+      "types": "./app/composables/useGscSitemapHistory.ts",
+      "import": "./app/composables/useGscSitemapHistory.ts",
+      "default": "./app/composables/useGscSitemapHistory.ts"
+    },
+    "./composables/useGscSitemaps": {
+      "types": "./app/composables/useGscSitemaps.ts",
+      "import": "./app/composables/useGscSitemaps.ts",
+      "default": "./app/composables/useGscSitemaps.ts"
+    },
+    "./composables/useGscTableState": {
+      "types": "./app/composables/useGscTableState.ts",
+      "import": "./app/composables/useGscTableState.ts",
+      "default": "./app/composables/useGscTableState.ts"
     }
   },
   "main": "./nuxt.config.ts",
@@ -47,20 +177,22 @@
   },
   "dependencies": {
     "@duckdb/duckdb-wasm": "^1.32.0",
-    "@nuxt/ui": "^4.7.1",
+    "@nuxt/ui": "^4.8.0",
     "@unovis/ts": "^1.6.5",
     "@unovis/vue": "^1.6.5",
     "@vueuse/core": "^14.3.0",
     "@vueuse/nuxt": "^14.3.0",
     "defu": "^6.1.7",
+    "nuxt-use-query": "^0.2.4",
     "ofetch": "^1.5.1",
     "tailwindcss": "^4.3.0",
-    "@gscdump/analysis": "0.21.3",
-    "@gscdump/contracts": "0.21.3",
-    "@gscdump/engine": "0.21.3",
-    "@gscdump/engine-duckdb-wasm": "0.21.3",
-    "gscdump": "0.21.3",
-    "@gscdump/sdk": "0.21.3"
+    "zod": "^4.4.3",
+    "@gscdump/analysis": "0.22.4",
+    "@gscdump/contracts": "0.22.4",
+    "@gscdump/engine": "0.22.4",
+    "@gscdump/engine-duckdb-wasm": "0.22.4",
+    "@gscdump/sdk": "0.22.4",
+    "gscdump": "0.22.4"
   },
   "devDependencies": {
     "@nuxt/kit": "^4.4.6",

package/types.ts

@@ -8,9 +8,9 @@
 
 import type { AnalyticsClient } from '@gscdump/sdk'
 import type { $Fetch } from 'ofetch'
-import type { GscQueryDispatcher } from './app/composables/_useGscQueryDispatcher'
 import type { GscAnalyticsContext } from './app/composables/useGscAnalytics'
 import type { GscAnalyzerDefinition } from './app/composables/useGscAnalyzerDefs'
+import type { GscQueryDispatcher } from './app/composables/useGscQueryDispatcher'
 
 export interface GscAnalyticsRuntimeConfig {
   /**
@@ -46,6 +46,7 @@ declare module '#app' {
   }
 }
 
+export type { GscAnalyzerInstance, GscAnalyzerTimings } from './app/composables/useGscAnalyzer'
 export type {
   GscAnalyzerBatchEntry,
   GscAnalyzerBatchRunner,
@@ -65,14 +66,9 @@ export type {
   GscAnalyzerPanelSpec,
   GscAnalyzerStatTile,
 } from './app/composables/useGscAnalyzerDefs'
-
 export { gscPanelRunnerKey, useGscPanelRunner } from './app/composables/useGscPanelContext'
 
 export type { GscPanelRunnerContext } from './app/composables/useGscPanelContext'
-export type {
-  UseGscParquetTableOptions,
-  UseGscParquetTableReturn,
-} from './app/composables/useGscParquetTable'
 
 export type {
   GscBackfillRunner,
@@ -85,7 +81,12 @@ export type {
   UseGscQueryReturn,
 } from './app/composables/useGscQuery'
 
-export type { UseGscRollupTableOptions } from './app/composables/useGscRollupTable'
+export type {
+  GscFactTable,
+  GscTableStage,
+  GscTableStatus,
+  UseGscSiteAnalyzerReturn,
+} from './app/composables/useGscSiteAnalyzer'
 
 export type {
   AnalysisSourcesResponse,

package/app/composables/useGscEngine.ts

@@ -1,16 +0,0 @@
-// App-wide engine override for `useGscQuery`. SSR-safe via `useState`.
-//
-// Resolution priority lives in `useGscQueryDispatcher.pickEngine`:
-//   per-call `opts.engine` → `useGscEngine().value` → `runtimeConfig.public.
-//   analytics.defaultEngine` → `'auto'`.
-//
-// Set the value once on the consumer side (e.g. from your auth plugin's
-// `onReady` hook reading a per-user feature flag) and every query inherits.
-
-import type { GscQueryEngine } from './useGscQuery'
-
-const STATE_KEY = 'gscdump:engine'
-
-export function useGscEngine(): Ref<GscQueryEngine | null> {
-  return useState<GscQueryEngine | null>(STATE_KEY, () => null)
-}

package/app/composables/useGscParquetTable.ts

@@ -1,199 +0,0 @@
-// Parquet-attached DuckDB table view: fuzzy-search + sortable metrics +
-// pagination over a single attached parquet (`main.<table>`), date-filtered.
-//
-// Sibling of `useGscRollupTable` — the rollup variant fetches a precomputed
-// JSON payload; this variant fires SQL against a parquet view in the
-// browser-attached DuckDB-WASM runtime. Two callers today (analyze.vue's
-// `pages` and `keywords` raw tabs); third+ callers are mechanical.
-//
-// Caller passes the `query` fn from `useGscAnalyzer(siteId)`; the composable
-// owns the SQL builder, the debounce, the watcher, and the count+page
-// Promise.all. It does NOT own `period`/`sort`/`page`/`q` — those are passed
-// in so callers can deep-link and share state (the `/analyze` page wires one
-// `useGscTableState` across raw + analyzer tabs).
-
-import type { MaybeRefOrGetter, Ref } from '@vue/runtime-core'
-import type { GscSortState } from './useGscTableState'
-
-interface QueryResult { rows: Record<string, unknown>[], queryMs: number }
-
-export interface UseGscParquetTableOptions {
-  /** Attached view name in `main.<table>` (e.g. `pages`, `keywords`). */
-  table: MaybeRefOrGetter<string>
-  /** Dimension column rows group by + fuzzy-search against. */
-  dim: MaybeRefOrGetter<string>
-  /** `useGscAnalyzer(siteId).query`. */
-  query: (sql: string, params?: unknown[]) => Promise<QueryResult>
-  /** Date window applied as `date BETWEEN ? AND ?`. */
-  dateRange: MaybeRefOrGetter<{ start: string, end: string }>
-  /**
-   * External table state — search, sort, page, pageSize. Usually a shared
-   *  `useGscTableState()` so URL deep-links survive tab switches.
-   */
-  q: Ref<string>
-  sort: Ref<GscSortState | null>
-  page: Ref<number>
-  pageSize: Ref<number>
-  /** Gate firing the query until the underlying runtime is ready. */
-  ready: MaybeRefOrGetter<boolean>
-  /** Re-fire whenever any of these change. (Period state, stableData flag, …) */
-  triggers?: MaybeRefOrGetter<unknown>[]
-  /** Search debounce. Default 200ms. */
-  debounceMs?: number
-}
-
-export interface UseGscParquetTableReturn {
-  rows: Ref<Record<string, unknown>[]>
-  totalRows: Ref<number | null>
-  totalPages: Ref<number | null>
-  queryMs: Ref<number | null>
-  loading: Ref<boolean>
-  error: Ref<string | null>
-}
-
-const SQL_SORT_COLS = new Set(['clicks', 'impressions', 'ctr', 'avg_position'])
-const WHITESPACE_RE = /\s+/
-
-function tokenize(s: string): string[] {
-  const seen = new Set<string>()
-  const out: string[] = []
-  for (const t of s.trim().split(WHITESPACE_RE).filter(Boolean)) {
-    const lower = t.toLowerCase()
-    if (!seen.has(lower)) {
-      seen.add(lower)
-      out.push(lower)
-    }
-  }
-  return out
-}
-
-interface SearchClauses { where: string, rank: string, params: unknown[] }
-
-function buildSearchClauses(dim: string, tokens: string[]): SearchClauses {
-  if (tokens.length === 0)
-    return { where: '', rank: '', params: [] }
-  const patterns = tokens.map(t => `%${t}%`)
-  const ors = tokens.map(() => `${dim} ILIKE ?`).join(' OR ')
-  const cases = tokens.map(() => `(CASE WHEN ${dim} ILIKE ? THEN 1 ELSE 0 END)`).join(' + ')
-  return {
-    where: `WHERE (${ors})`,
-    rank: `${cases} DESC,`,
-    params: [...patterns, ...patterns],
-  }
-}
-
-function withDateFilter(
-  searchWhere: string,
-  searchParams: unknown[],
-  start: string,
-  end: string,
-): { where: string, params: unknown[] } {
-  const dateClause = 'date BETWEEN ? AND ?'
-  const where = searchWhere ? `${searchWhere} AND ${dateClause}` : `WHERE ${dateClause}`
-  return { where, params: [...searchParams, start, end] }
-}
-
-function sortKey(dim: string, sort: GscSortState | null): string {
-  const col = sort?.column ?? 'clicks'
-  if (SQL_SORT_COLS.has(col))
-    return col
-  if (col === dim)
-    return dim
-  return 'clicks'
-}
-
-export function useGscParquetTable(opts: UseGscParquetTableOptions): UseGscParquetTableReturn {
-  const rows = ref<Record<string, unknown>[]>([])
-  const totalRows = ref<number | null>(null)
-  const queryMs = ref<number | null>(null)
-  const loading = ref(false)
-  const error = ref<string | null>(null)
-
-  const searchDebounced = ref('')
-  let handle: ReturnType<typeof setTimeout> | null = null
-  watch(opts.q, (v: string) => {
-    if (handle)
-      clearTimeout(handle)
-    handle = setTimeout(() => {
-      searchDebounced.value = v
-    }, opts.debounceMs ?? 200)
-  })
-
-  async function run(): Promise<void> {
-    if (!toValue(opts.ready))
-      return
-    const table = toValue(opts.table)
-    const dim = toValue(opts.dim)
-    const { start, end } = toValue(opts.dateRange)
-    const tokens = tokenize(searchDebounced.value)
-    const { where: searchWhere, rank, params: searchParams } = buildSearchClauses(dim, tokens)
-    const dir = (opts.sort.value?.direction ?? 'desc').toUpperCase()
-    const limit = opts.pageSize.value
-    const offset = (opts.page.value - 1) * limit
-
-    const wherePart = withDateFilter(searchWhere, searchParams.slice(0, tokens.length), start, end)
-    const rankParams = searchParams.slice(tokens.length)
-
-    const pageSql = `
-      SELECT ${dim},
-             SUM(clicks)::BIGINT AS clicks,
-             SUM(impressions)::BIGINT AS impressions,
-             CASE WHEN SUM(impressions) > 0
-                  THEN ROUND(SUM(clicks) * 1.0 / SUM(impressions), 4)
-                  ELSE 0 END AS ctr,
-             CASE WHEN SUM(impressions) > 0
-                  THEN ROUND(SUM(sum_position) / SUM(impressions) + 1, 2)
-                  ELSE 0 END AS avg_position
-      FROM main.${table}
-      ${wherePart.where}
-      GROUP BY ${dim}
-      ORDER BY ${rank} ${sortKey(dim, opts.sort.value)} ${dir}
-      LIMIT ${limit} OFFSET ${offset}
-    `
-    const countSql = `SELECT COUNT(DISTINCT ${dim})::BIGINT AS n FROM main.${table} ${wherePart.where}`
-
-    loading.value = true
-    error.value = null
-    rows.value = []
-    queryMs.value = null
-    try {
-      const [pageRes, countRes] = await Promise.all([
-        opts.query(pageSql, [...wherePart.params, ...rankParams]),
-        opts.query(countSql, wherePart.params),
-      ])
-      rows.value = pageRes.rows
-      queryMs.value = pageRes.queryMs
-      const n = countRes.rows[0]?.n
-      totalRows.value = typeof n === 'bigint' ? Number(n) : typeof n === 'number' ? n : null
-    }
-    catch (err) {
-      error.value = err instanceof Error ? err.message : String(err)
-    }
-    finally {
-      loading.value = false
-    }
-  }
-
-  const triggerSources = [
-    () => toValue(opts.ready),
-    () => toValue(opts.table),
-    () => toValue(opts.dim),
-    () => toValue(opts.dateRange),
-    opts.sort,
-    opts.page,
-    opts.pageSize,
-    searchDebounced,
-    ...(opts.triggers ?? []).map(t => () => toValue(t as MaybeRefOrGetter<unknown>)),
-  ]
-  watch(triggerSources, () => {
-    void run()
-  })
-
-  const totalPages = computed(() => {
-    if (totalRows.value == null)
-      return null
-    return Math.max(1, Math.ceil(totalRows.value / opts.pageSize.value))
-  })
-
-  return { rows, totalRows, totalPages, queryMs, loading, error }
-}