@gscdump/nuxt 0.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Harlan Wilton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# @gscdump/nuxt
+
+[![npm version](https://img.shields.io/npm/v/@gscdump/nuxt?color=yellow)](https://npmjs.com/package/@gscdump/nuxt)
+[![npm downloads](https://img.shields.io/npm/dm/@gscdump/nuxt?color=yellow)](https://npm.chart.dev/@gscdump/nuxt)
+[![license](https://img.shields.io/github/license/harlan-zw/gscdump?color=yellow)](https://github.com/harlan-zw/gscdump/blob/main/LICENSE)
+
+> Nuxt layer: GSC analytics UI, Nuxt auth/runtime wiring, and DuckDB-WASM integration. It uses `@gscdump/sdk` internally for hosted analytics HTTP reads.
+
+This package assumes a site is already linked. It does not own partner
+onboarding, registration, lifecycle decisions, token exchange, or webhook
+subscription management. Use `@gscdump/sdk` from the host app for those
+flows, then pass the linked `gscdumpSiteId` into the analytics composables
+here.
+
+Three consumption modes:
+
+| Mode | Who | What it does |
+| --- | --- | --- |
+| `origin` | gscdump.com | Reads R2 data directly (binding) + DuckDB service binding. Owns the data. |
+| `consumer` | nuxtseo.com | Proxies all reads to an origin over HTTP + an API key. No data locally. |
+| `local` | `examples/nuxt-dashboard` | Reads a `gscdump sync` dump from `GSCDUMP_DATA_DIR`. Offline dev. |
+
+## Install
+
+```bash
+pnpm add @gscdump/nuxt
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@gscdump/nuxt'],
+  runtimeConfig: {
+    analytics: {
+      mode: 'origin', // or 'consumer' / 'local'
+    },
+  },
+})
+```
+
+## Register an auth provider
+
+```ts
+// server/plugins/register-auth.ts
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook('analytics:register-auth-provider', (register) => {
+    register({
+      resolve: async (event) => {
+        const session = await getUserSession(event)
+        if (!session)
+          return null
+        return { userId: session.user.id, siteIds: session.accessibleSiteIds }
+      },
+    })
+  })
+})
+```
+
+## Data access: which endpoint?
+
+| 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(...)` |
+
+Rule of thumb: reach for `/rows` + `useGscRowQuery` 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.
+
+## Consumer mode (cross-origin)
+
+Used when the Nuxt app authenticating the viewer is not the same origin as
+the data — e.g. nuxtseo.com pro consuming gscdump.com. Two pieces:
+
+1. **Point fetch at the origin**: set `runtimeConfig.public.analytics.apiBase`
+   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`
+   attaches the header to every `/api/__gsc/*` call automatically. The same
+   header rides parquet GETs in `attachParquetUrlTables` (DuckDB-WASM
+   browser path), so R2 reads work cross-origin.
+
+The `setupGscFetchAuth` helper collapses the boilerplate:
+
+```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
+  },
+})
+```
+
+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`.
+
+Onboarding and lifecycle state stay outside this layer. A consumer app should
+use `@gscdump/sdk` from its host backend to register users/sites, read
+`GET /api/partner/users/:userId/lifecycle`, handle webhook or realtime
+invalidation, and decide when a linked site is ready to render. Once it has a
+linked site id, this layer handles query reads and analytics UI only.
+
+### CORS
+
+The origin app (`gscdump.com` or your own) must allow the consumer origin
+on `/api/__gsc/*`, `/api/r2-data/*`, and any host endpoints the helper
+calls. Allow-headers must include `x-api-key`, `Cache-Control`, and `Range`
+(DuckDB-WASM uses partial reads); expose `Content-Range`, `Accept-Ranges`,
+`Content-Length`. Preflight needs to cover `PATCH` for any settings calls.
+
+## Related
+
+- [`@gscdump/sdk`](../sdk) — framework-agnostic hosted API client used by host onboarding code and by this Nuxt layer internally.
+- [`gscdump`](../gscdump) — local package and query builder.
+- [`@gscdump/engine`](../engine) — Storage engine consumed in origin mode.
+- [`@gscdump/engine-duckdb-wasm`](../engine-duckdb-wasm) — DuckDB-WASM browser runtime used by client-side widgets.
+- [`@gscdump/analysis`](../analysis) — Analyzers powering `/analyze` endpoints.
+
+## License
+
+[MIT](../../LICENSE)

package/app/assets/css/main.css

@@ -0,0 +1,2 @@
+@import "tailwindcss";
+@import "@nuxt/ui";

package/app/components/GscAnalyzerPanel.vue

@@ -0,0 +1,94 @@
+<script setup lang="ts">
+// Unified shell for `/analyze` analyzer tabs. Drives the chrome that 11
+// per-analyzer sections used to repeat: stat tiles, body, caption. The body
+// component + tile projection + caption come from `def.capabilities.panel`;
+// the shell owns the loading/error/empty gating unless `panel.ownsLifecycle`
+// is set (pipeline panels manage their own phase state internally).
+
+import type {
+  GscAnalyzerDefinition,
+  GscAnalyzerPanelResult,
+} from '../composables/useGscAnalyzerDefs'
+
+interface Props {
+  def: GscAnalyzerDefinition
+  rows: unknown[]
+  meta: Record<string, unknown> | null
+  queryMs?: number | null
+  loading?: boolean
+  error?: string | null
+  /** Forwarded to the body component as `range`. Optional. */
+  range?: { start: string, end: string } | null
+}
+
+const props = defineProps<Props>()
+
+const panel = computed(() => props.def.capabilities?.panel)
+
+const tiles = computed(() => {
+  const p = panel.value
+  if (!p?.summarize)
+    return []
+  const result: GscAnalyzerPanelResult = {
+    results: props.rows,
+    meta: props.meta ?? {},
+    queryMs: props.queryMs ?? null,
+  }
+  return p.summarize(result)
+})
+
+const showBody = computed(() => {
+  if (!panel.value)
+    return false
+  if (panel.value.ownsLifecycle)
+    return true
+  return !props.loading && !props.error && props.rows.length > 0
+})
+
+const bodyProps = computed(() => ({
+  rows: props.rows,
+  meta: props.meta ?? {},
+  range: props.range ?? null,
+}))
+</script>
+
+<template>
+  <section v-if="panel" class="gsc-analyzer-panel">
+    <div v-if="tiles.length > 0" class="gsc-analyzer-panel__tiles">
+      <div v-for="(t, i) in tiles" :key="`${t.label}-${i}`" class="gsc-analyzer-panel__tile">
+        <span class="gsc-analyzer-panel__tile-label">{{ t.label }}</span>
+        <span class="gsc-analyzer-panel__tile-value" :style="t.valueColor ? { color: t.valueColor } : undefined">{{ t.value }}</span>
+      </div>
+    </div>
+
+    <template v-if="!panel.ownsLifecycle">
+      <div v-if="error" class="gsc-analyzer-panel__error">
+        {{ error }}
+      </div>
+      <div v-else-if="loading" class="gsc-analyzer-panel__loading">
+        Running analyzer…
+      </div>
+      <div v-else-if="rows.length === 0" class="gsc-analyzer-panel__empty">
+        No rows.
+      </div>
+    </template>
+
+    <component :is="panel.component" v-if="showBody" v-bind="bodyProps" />
+
+    <p v-if="panel.caption" class="gsc-analyzer-panel__caption">
+      <slot name="caption">{{ panel.caption }}</slot>
+    </p>
+  </section>
+</template>
+
+<style scoped>
+.gsc-analyzer-panel { background: #fff; border: 1px solid #ececef; border-top: 0; border-radius: 0 0 6px 6px; padding: 1rem 1rem 0.9rem; }
+.gsc-analyzer-panel__tiles { display: flex; gap: 1.5rem; flex-wrap: wrap; margin-bottom: 0.85rem; padding: 0 0.15rem; }
+.gsc-analyzer-panel__tile { display: flex; flex-direction: column; gap: 0.1rem; }
+.gsc-analyzer-panel__tile-label { font-size: 0.66rem; letter-spacing: 0.08em; text-transform: uppercase; color: #888; }
+.gsc-analyzer-panel__tile-value { font-size: 1.3rem; font-weight: 600; color: #1d1d1f; font-variant-numeric: tabular-nums; }
+.gsc-analyzer-panel__caption { margin: 0.8rem 0 0; font-size: 0.78rem; color: #666; font-style: italic; text-align: center; }
+.gsc-analyzer-panel__caption :deep(code) { background: #f0f0f3; padding: 0.05rem 0.3rem; border-radius: 3px; font-size: 0.74rem; color: #4c3ca0; }
+.gsc-analyzer-panel__error { padding: 1rem 1.25rem; color: #c00; background: #fff5f5; font-family: ui-monospace, monospace; font-size: 0.82rem; white-space: pre-wrap; }
+.gsc-analyzer-panel__loading, .gsc-analyzer-panel__empty { padding: 2.5rem; text-align: center; color: var(--ui-text-dimmed); font-size: 0.9rem; }
+</style>

package/app/components/GscAnonymizationBanner.vue

@@ -0,0 +1,46 @@
+<script setup lang="ts">
+// Surfaces the trailing-28d impression-weighted anonymization % from the
+// daily_totals rollup. GSC anonymises queries for low-volume or sensitive
+// terms, so query-grained breakdowns (keywords, pages-by-query) undercount
+// impressions by this amount. Hidden when data isn't ready or the gap is
+// negligible (<1%).
+
+import { useGscRollup } from '../composables/useGscRollup'
+import { weightedAnonPct } from '../utils/anonymization'
+
+interface DailyTotal {
+  impressions: number
+  anonymizedImpressionsPct: number
+}
+
+const { siteIdentifier } = defineProps<{
+  siteIdentifier: string | null | undefined
+}>()
+
+const { data: daily } = useGscRollup<DailyTotal[]>(() => siteIdentifier ?? null, 'daily_totals')
+
+const formatted = computed(() => {
+  if (!siteIdentifier)
+    return null
+  const pct = weightedAnonPct(daily.value)
+  if (pct == null)
+    return null
+  const percent = pct * 100
+  if (percent < 1)
+    return null
+  return percent.toFixed(percent < 10 ? 1 : 0)
+})
+</script>
+
+<template>
+  <div
+    v-if="formatted"
+    class="flex items-start gap-2 border border-amber-500/30 bg-amber-500/5 px-3 py-2 text-xs text-amber-200/90"
+  >
+    <UIcon name="i-ph-info" class="mt-0.5 flex-shrink-0 text-amber-400" />
+    <div>
+      <span class="font-semibold">~{{ formatted }}% of impressions are anonymised by Google.</span>
+      Query-grained breakdowns below exclude these, so the sum won't match site-level totals.
+    </div>
+  </div>
+</template>

package/app/components/GscBootProgress.vue

@@ -0,0 +1,297 @@
+<script setup lang="ts">
+// Minimal boot-progress indicator for the browser-side DuckDB-WASM + parquet
+// attach flow. Reads per-site progress straight off the injected analyzer
+// state (`siteProgress` on `BrowserAnalyzerState`) — no derived composable,
+// no prop drilling.
+//
+// Collapsed view: one slim stacked bar, each segment a site, coloured by
+// stage. Tap to expand per-site rows with file counters. Hidden once every
+// tracked site is ready.
+
+import type { SiteLoadProgress, SiteLoadStage } from '../composables/useGscAnalytics'
+import { useGscBootProgress } from '../composables/useGscAnalytics'
+
+// Reads the shared per-site progress ref directly. Both DuckDB boot and rollup
+// fan-out write to it, so this component lights up for either flow without
+// caring who's producing the signal.
+const { progress: siteProgress } = useGscBootProgress()
+
+const expanded = ref(false)
+
+const sites = computed<SiteLoadProgress[]>(() =>
+  Object.values(siteProgress.value).sort((a, b) => a.startedAt - b.startedAt),
+)
+
+const allReady = computed(() => sites.value.length > 0 && sites.value.every(s => s.stage === 'ready'))
+const anyActive = computed(() => sites.value.some(s => s.stage !== 'ready' && s.stage !== 'idle' && s.stage !== 'error'))
+
+const aggregate = computed(() => {
+  let attached = 0
+  let total = 0
+  for (const s of sites.value) {
+    attached += s.filesAttached
+    total += s.filesTotal
+  }
+  return { attached, total, pct: total > 0 ? Math.round((attached / total) * 100) : 0 }
+})
+
+// Rank stages so the earliest-stage site drives the overall headline.
+const stageRank: Record<SiteLoadStage, number> = {
+  idle: 0,
+  wasm: 1,
+  manifest: 2,
+  attach: 3,
+  ready: 4,
+  error: -1,
+}
+
+const earliestStage = computed<SiteLoadStage>(() => {
+  let min: SiteLoadStage = 'ready'
+  let minRank = stageRank.ready
+  for (const s of sites.value) {
+    const r = stageRank[s.stage]
+    if (r >= 0 && r < minRank) {
+      min = s.stage
+      minRank = r
+    }
+  }
+  return min
+})
+
+const stageLabel: Record<SiteLoadStage, string> = {
+  idle: 'Queued',
+  wasm: 'Starting DuckDB',
+  manifest: 'Fetching manifest',
+  attach: 'Attaching parquet',
+  ready: 'Ready',
+  error: 'Error',
+}
+
+const stageColor: Record<SiteLoadStage, string> = {
+  idle: 'bg-neutral-700',
+  wasm: 'bg-violet-500',
+  manifest: 'bg-sky-500',
+  attach: 'bg-emerald-500',
+  ready: 'bg-emerald-600',
+  error: 'bg-rose-500',
+}
+
+function siteWidth(site: SiteLoadProgress): string {
+  if (site.stage === 'ready')
+    return '100%'
+  if (site.filesTotal === 0)
+    // No file count yet (wasm / manifest phase) — show a fractional sliver so
+    // the segment is visible but clearly not done.
+    return site.stage === 'wasm' ? '10%' : '25%'
+  return `${Math.max(5, Math.round((site.filesAttached / site.filesTotal) * 100))}%`
+}
+
+function truncate(id: string, max = 28): string {
+  if (id.length <= max)
+    return id
+  return `${id.slice(0, max - 1)}…`
+}
+</script>
+
+<template>
+  <Transition
+    enter-active-class="transition-all duration-200"
+    enter-from-class="opacity-0 translate-y-[-4px]"
+    enter-to-class="opacity-100 translate-y-0"
+    leave-active-class="transition-all duration-300"
+    leave-from-class="opacity-100"
+    leave-to-class="opacity-0"
+  >
+    <div
+      v-if="!allReady && sites.length > 0"
+      class="analytics-boot-progress"
+    >
+      <button
+        type="button"
+        class="headline"
+        :aria-expanded="expanded"
+        @click="expanded = !expanded"
+      >
+        <span class="dot" :class="stageColor[earliestStage]" />
+        <span class="label">{{ stageLabel[earliestStage] }}</span>
+        <span class="counter">
+          <template v-if="aggregate.total > 0">
+            {{ aggregate.attached }} / {{ aggregate.total }}
+          </template>
+          <template v-else>
+            {{ sites.length }} site{{ sites.length === 1 ? '' : 's' }}
+          </template>
+        </span>
+        <span class="caret" :class="{ open: expanded }">⌄</span>
+      </button>
+
+      <div class="bar">
+        <div
+          v-for="site in sites"
+          :key="site.siteId"
+          class="seg"
+          :class="[stageColor[site.stage], { shimmer: anyActive && site.stage !== 'ready' && site.stage !== 'error' }]"
+          :style="{ width: siteWidth(site) }"
+          :title="`${site.siteId}: ${stageLabel[site.stage]}`"
+        />
+      </div>
+
+      <Transition
+        enter-active-class="transition-all duration-200"
+        enter-from-class="opacity-0 max-h-0"
+        enter-to-class="opacity-100 max-h-[400px]"
+        leave-active-class="transition-all duration-150"
+        leave-from-class="opacity-100 max-h-[400px]"
+        leave-to-class="opacity-0 max-h-0"
+      >
+        <ul v-if="expanded" class="rows">
+          <li v-for="site in sites" :key="site.siteId" class="row">
+            <span class="row-dot" :class="stageColor[site.stage]" />
+            <span class="row-id">{{ truncate(site.siteId) }}</span>
+            <span class="row-stage">{{ stageLabel[site.stage] }}</span>
+            <span class="row-count">
+              <template v-if="site.filesTotal > 0">
+                {{ site.filesAttached }}/{{ site.filesTotal }}
+              </template>
+              <template v-else-if="site.stage === 'ready' && site.endedAt">
+                {{ Math.round(site.endedAt - site.startedAt) }}ms
+              </template>
+              <template v-else-if="site.stage === 'error'">
+                <span class="err">{{ truncate(site.error ?? 'error', 40) }}</span>
+              </template>
+              <template v-else>
+                —
+              </template>
+            </span>
+          </li>
+        </ul>
+      </Transition>
+    </div>
+  </Transition>
+</template>
+
+<style scoped>
+.analytics-boot-progress {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 8px 10px;
+  border: 1px solid rgba(255, 255, 255, 0.06);
+  background: rgba(255, 255, 255, 0.02);
+  border-radius: 4px;
+  font-size: 12px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+.headline {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  background: transparent;
+  border: 0;
+  padding: 0;
+  color: inherit;
+  cursor: pointer;
+  text-align: left;
+  width: 100%;
+}
+.dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 999px;
+  flex-shrink: 0;
+}
+.label {
+  color: rgba(255, 255, 255, 0.82);
+  font-weight: 500;
+}
+.counter {
+  color: rgba(255, 255, 255, 0.55);
+  margin-left: auto;
+  font-variant-numeric: tabular-nums;
+}
+.caret {
+  display: inline-block;
+  color: rgba(255, 255, 255, 0.4);
+  transition: transform 180ms ease;
+  width: 10px;
+  text-align: center;
+}
+.caret.open {
+  transform: rotate(180deg);
+}
+.bar {
+  display: flex;
+  gap: 2px;
+  height: 3px;
+  width: 100%;
+  overflow: hidden;
+  border-radius: 2px;
+  background: rgba(255, 255, 255, 0.04);
+}
+.seg {
+  height: 100%;
+  border-radius: 2px;
+  transition: width 220ms cubic-bezier(0.22, 0.61, 0.36, 1);
+  min-width: 4px;
+  position: relative;
+}
+.seg.shimmer::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(
+    90deg,
+    rgba(255, 255, 255, 0) 0%,
+    rgba(255, 255, 255, 0.28) 50%,
+    rgba(255, 255, 255, 0) 100%
+  );
+  animation: boot-shimmer 1.4s linear infinite;
+}
+@keyframes boot-shimmer {
+  from { transform: translateX(-100%); }
+  to { transform: translateX(100%); }
+}
+.rows {
+  list-style: none;
+  margin: 4px 0 0;
+  padding: 0;
+  overflow: hidden;
+}
+.row {
+  display: grid;
+  grid-template-columns: 10px minmax(0, 1fr) auto auto;
+  gap: 8px;
+  align-items: center;
+  padding: 3px 0;
+  color: rgba(255, 255, 255, 0.72);
+}
+.row + .row {
+  border-top: 1px solid rgba(255, 255, 255, 0.04);
+}
+.row-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 999px;
+  margin-left: 2px;
+}
+.row-id {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: rgba(255, 255, 255, 0.88);
+}
+.row-stage {
+  color: rgba(255, 255, 255, 0.5);
+  font-size: 11px;
+}
+.row-count {
+  color: rgba(255, 255, 255, 0.7);
+  font-variant-numeric: tabular-nums;
+  font-size: 11px;
+  min-width: 60px;
+  text-align: right;
+}
+.row-count .err {
+  color: #fb7185;
+}
+</style>

package/app/components/GscCommandPalette.vue

@@ -0,0 +1,77 @@
+<script setup lang="ts">
+// Cmd+K palette. Wraps UCommandPalette inside a UModal, wires up the global
+// keyboard shortcut, and sources its items from the analytics context + a
+// static list of top-level routes. Drop `<GscCommandPalette />` into your
+// root layout once.
+//
+// Hosts can extend the groups via the `groups` prop — e.g. nuxtseo.com adds
+// its billing / settings entries without forking the component.
+
+import type { CommandPaletteGroup, CommandPaletteItem } from '@nuxt/ui'
+import type { SiteListItem } from '../composables/useGscAnalytics'
+import { useMagicKeys, whenever } from '@vueuse/core'
+import { useGscSites } from '../composables/useGscAnalytics'
+
+const { groups: extraGroups = [] } = defineProps<{
+  groups?: CommandPaletteGroup[]
+}>()
+
+const router = useRouter()
+const { sites } = useGscSites()
+
+const open = ref(false)
+const selected = ref<CommandPaletteItem | null>(null)
+
+const keys = useMagicKeys()
+const cmdK = computed(() => keys.meta_k?.value || keys.ctrl_k?.value || false)
+whenever(cmdK, () => {
+  open.value = !open.value
+})
+
+const siteGroup = computed<CommandPaletteGroup<CommandPaletteItem>>(() => ({
+  id: 'sites',
+  label: 'Sites',
+  items: (sites.value ?? []).map<CommandPaletteItem>((s: SiteListItem) => ({
+    label: s.hostname,
+    suffix: s.propertyType === 'domain' ? 'sc-domain' : 'url-prefix',
+    icon: 'i-lucide-globe',
+    to: `/sites/${encodeURIComponent(s.id)}`,
+  })),
+}))
+
+const navGroup: CommandPaletteGroup<CommandPaletteItem> = {
+  id: 'nav',
+  label: 'Navigation',
+  items: [
+    { label: 'Overview', icon: 'i-lucide-layout-dashboard', to: '/' },
+  ],
+}
+
+const allGroups = computed<CommandPaletteGroup[]>(() => [
+  siteGroup.value,
+  navGroup,
+  ...extraGroups,
+])
+
+watch(selected, (item) => {
+  if (!item)
+    return
+  if (typeof item.to === 'string')
+    router.push(item.to)
+  open.value = false
+  selected.value = null
+})
+</script>
+
+<template>
+  <UModal v-model:open="open" :ui="{ content: 'max-w-[560px]' }">
+    <template #content>
+      <UCommandPalette
+        v-model="selected"
+        :groups="allGroups"
+        placeholder="Jump to a site or action…"
+        class="h-[420px]"
+      />
+    </template>
+  </UModal>
+</template>