@pilotiq/pilotiq 0.1.0

package/src/vite.ts

@@ -0,0 +1,758 @@
+/**
+ * Vite plugin that generates Vike page stubs for @pilotiq/pilotiq.
+ *
+ * Stubs are written at plugin construction time (before Vike scans pages/).
+ * They use route functions that check PilotiqRegistry at request time, so
+ * they work for any number of registered panels without regeneration.
+ *
+ * The plugin also reads the user's panel module(s) (default
+ * `app/Pilotiq/AdminPanel`) and emits `pages/(pilotiq)/_components.ts`,
+ * a re-export manifest of every Resource/Global/Page class registered
+ * across all panels. The auto-gen `+Layout.tsx` imports the manifest
+ * so component-typed icons (`Resource.icon = SomeIcon`) resolve at
+ * render time.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { createJiti } from 'jiti'
+import type { Plugin } from 'vite'
+
+export interface PilotiqVitePluginOptions {
+  /**
+   * Path(s) to module(s) exporting `Pilotiq` instances. The plugin
+   * imports each path and walks `panel.getConfig().resources / globals /
+   * pages` to build the component manifest.
+   *
+   * Paths are resolved relative to the Vite config's project root.
+   * Defaults to `['./app/Pilotiq/AdminPanel']` (the convention used by
+   * the playgrounds). Override only if your panel module lives elsewhere.
+   *
+   * Panel files must be import-safe — top-level code must not run
+   * server-only logic (db queries, `node:fs`, etc.). Builder calls and
+   * class definitions are fine.
+   */
+  panels?: string | string[]
+}
+
+function writeIfChanged(filePath: string, contents: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  if (fs.existsSync(filePath)) {
+    const existing = fs.readFileSync(filePath, 'utf8')
+    if (existing === contents) return
+  }
+  fs.writeFileSync(filePath, contents)
+}
+
+function generatePages(pagesRoot: string): void {
+  const outDir = path.join(pagesRoot, '(pilotiq)')
+
+  // Shared config
+  writeIfChanged(path.join(outDir, '+config.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { Config } from 'vike/types'
+
+export default {
+  // 'viewProps' is set by the rudder server handler via view().
+  // 'data' is the Vike +data() return value — populated on SPA nav.
+  // Page renderers read from data ?? viewProps so both paths work.
+  passToClient: ['viewProps', 'data'],
+} satisfies Config
+`)
+
+  // Shared data hook — runs server-side on every page load and on every
+  // SPA navigation. SSR path: rudder's route handler already populated
+  // viewProps via view(), so we hand it back. SPA path: only +data runs,
+  // so we build the schema ourselves through dispatchPageData.
+  const dataStub = `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { PageContextServer } from 'vike/types'
+import { dispatchPageData } from '@pilotiq/pilotiq'
+
+export const data = async (pageContext: PageContextServer): Promise<unknown> => {
+  const viewProps = (pageContext as unknown as { viewProps?: unknown }).viewProps
+  if (viewProps !== undefined) return viewProps
+  return dispatchPageData(pageContext as Parameters<typeof dispatchPageData>[0])
+}
+`
+
+  // ── Head — FOUC prevention + render-hook slots ────────────
+  const headContent = [
+    '// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.',
+    "import { usePageContext } from 'vike-react/usePageContext'",
+    "import { HeadHooks } from '@pilotiq/pilotiq/react'",
+    '',
+    '// Fontshare hosts Satoshi (Pilotiq brand font). Google Fonts is the fallback',
+    '// for any other family configured via Pilotiq.theme({ fonts }).',
+    'const FONTSHARE_FAMILIES: Record<string, string> = {',
+    "  Satoshi: 'https://api.fontshare.com/v2/css?f[]=satoshi@300,500,700&display=swap',",
+    '}',
+    '',
+    'export default function PilotiqHead() {',
+    '  let fontFamilies: string[] = []',
+    '  let renderHooks: any = undefined',
+    '',
+    '  try {',
+    '    const ctx = usePageContext() as unknown as { viewProps?: Record<string, unknown>; data?: Record<string, unknown> }',
+    '    const panel = ((ctx.data ?? ctx.viewProps) as any)?.panel',
+    '    const theme = panel?.theme',
+    '    const fonts = theme?.fonts',
+    '    if (fonts) {',
+    '      const seen = new Set<string>()',
+    '      if (fonts.body) seen.add(fonts.body)',
+    '      if (fonts.heading && !seen.has(fonts.heading)) seen.add(fonts.heading)',
+    '      fontFamilies = [...seen]',
+    '    }',
+    '    renderHooks = panel?.renderHooks',
+    '  } catch {',
+    '    // pageContext may not be available in all render contexts',
+    '  }',
+    '',
+    '  const fontshareLinks: string[] = []',
+    '  const googleFamilies: string[] = []',
+    '  for (const family of fontFamilies) {',
+    '    const fsHref = FONTSHARE_FAMILIES[family]',
+    '    if (fsHref) fontshareLinks.push(fsHref)',
+    '    else        googleFamilies.push(family)',
+    '  }',
+    '',
+    '  const googleHref = googleFamilies.length > 0',
+    '    ? `https://fonts.googleapis.com/css2?${googleFamilies.map((f: string) => `family=${f.replace(/ /g, \'+\')}:wght@400;500;600;700`).join(\'&\')}&display=swap`',
+    '    : null',
+    '',
+    '  return (',
+    '    <>',
+    '      <HeadHooks hooks={renderHooks} position="start" />',
+    '      {fontshareLinks.length > 0 && (',
+    '        <link rel="preconnect" href="https://api.fontshare.com" crossOrigin="" />',
+    '      )}',
+    '      {fontshareLinks.map((href: string) => (',
+    '        <link key={href} rel="stylesheet" href={href} />',
+    '      ))}',
+    '      {googleHref && (',
+    '        <>',
+    '          <link rel="preconnect" href="https://fonts.googleapis.com" />',
+    '          <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="" />',
+    '          <link rel="stylesheet" href={googleHref} />',
+    '        </>',
+    '      )}',
+    '      <script',
+    '        dangerouslySetInnerHTML={{',
+    "          __html: `(function(){try{var t=localStorage.getItem('pilotiq-theme');if(t==='dark'||(t!=='light'&&matchMedia('(prefers-color-scheme:dark)').matches)){document.documentElement.classList.add('dark')}}catch(e){}})()`",
+    '        }}',
+    '      />',
+    '      <HeadHooks hooks={renderHooks} position="end" />',
+    '    </>',
+    '  )',
+    '}',
+  ].join('\n')
+  writeIfChanged(path.join(outDir, '+Head.tsx'), headContent + '\n')
+
+  // Layout is written by writeLayoutWithManifest() — keeps the file in
+  // one place so the componentRegistry import line stays in sync.
+
+  // ── Dashboard ────────────────────────────────────────────
+  writeIfChanged(path.join(outDir, 'dashboard', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  if (parts.length !== 1) return false
+  if (import.meta.env.SSR && !PilotiqRegistry.findByPath('/' + parts[0])) return false
+  return { routeParams: { basePath: parts[0] } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'dashboard', '+data.ts'), dataStub)
+  writeIfChanged(path.join(outDir, 'dashboard', '+Page.tsx'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import { usePageContext } from 'vike-react/usePageContext'
+import { SchemaRenderer } from '@pilotiq/pilotiq/react'
+
+export default function PilotiqDashboard() {
+  const ctx = usePageContext() as unknown as { viewProps?: Record<string, unknown>; data?: Record<string, unknown> }
+  const { panel, basePath, schemaData, _widgetData } = (ctx.data ?? ctx.viewProps) as any ?? {}
+  const hasSchema = schemaData && schemaData.length > 0
+
+  if (hasSchema) return <SchemaRenderer elements={schemaData} widgetData={_widgetData} />
+
+  return (
+    <>
+      <h1 className="text-2xl font-bold mb-6">
+        {panel?.branding?.title ?? panel?.name} Dashboard
+      </h1>
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+        {panel?.resources?.map((r: any) => (
+          <a key={r.slug} href={basePath + '/' + r.slug}
+             className="block p-6 bg-white dark:bg-gray-800 rounded-xl border border-gray-200 dark:border-gray-700 hover:border-indigo-300 dark:hover:border-indigo-600 transition">
+            <h3 className="font-semibold text-gray-900 dark:text-gray-100">{r.label}</h3>
+            <p className="text-sm text-gray-500 dark:text-gray-400 mt-1">Manage {r.label.toLowerCase()}</p>
+          </a>
+        ))}
+      </div>
+    </>
+  )
+}
+`)
+
+  // ── Slug (resource index OR custom page OR Global edit) ────
+  // Single route for all 2-segment URLs (or 3-segment when prefixed by
+  // a cluster slug) — server disambiguates via pageType in viewProps.
+  writeIfChanged(path.join(outDir, 'slug', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+import { clusterOffset } from '../_clusterOffset.js'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  const off = clusterOffset(parts)
+  if (parts.length !== 2 + off) return false
+  // Don't match built-in slugs (theme editor, etc.)
+  if (parts[1 + off] === 'theme') return false
+  if (import.meta.env.SSR && !PilotiqRegistry.findByPath('/' + parts[0])) return false
+  return { routeParams: { basePath: parts[0], slug: parts[1 + off]! } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'slug', '+data.ts'), dataStub)
+  writeIfChanged(path.join(outDir, 'slug', '+Page.tsx'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import { usePageContext } from 'vike-react/usePageContext'
+import { SchemaRenderer } from '@pilotiq/pilotiq/react'
+
+export default function SlugPage() {
+  const ctx = usePageContext() as unknown as { viewProps?: Record<string, unknown>; data?: Record<string, unknown> }
+  const vp = (ctx.data ?? ctx.viewProps) as any ?? {}
+  return <SchemaRenderer elements={vp.schemaData ?? []} widgetData={vp._widgetData} />
+}
+`)
+
+  // ── Resource Create ───────────────────────────────────────
+  writeIfChanged(path.join(outDir, 'resource-create', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+import { clusterOffset } from '../_clusterOffset.js'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  const off = clusterOffset(parts)
+  if (parts.length !== 3 + off || parts[2 + off] !== 'create') return false
+  if (import.meta.env.SSR && !PilotiqRegistry.findByPath('/' + parts[0])) return false
+  return { routeParams: { basePath: parts[0], slug: parts[1 + off]! } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'resource-create', '+data.ts'), dataStub)
+
+  // ── Resource Edit ─────────────────────────────────────────
+  writeIfChanged(path.join(outDir, 'resource-edit', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+import { clusterOffset } from '../_clusterOffset.js'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  const off = clusterOffset(parts)
+  if (parts.length !== 4 + off || parts[3 + off] !== 'edit') return false
+  if (import.meta.env.SSR && !PilotiqRegistry.findByPath('/' + parts[0])) return false
+  return { routeParams: { basePath: parts[0], slug: parts[1 + off]!, id: parts[2 + off]! } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'resource-edit', '+data.ts'), dataStub)
+
+  // Create and Edit share the same schema-driven page component
+  const formPage = `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import { usePageContext } from 'vike-react/usePageContext'
+import { SchemaRenderer } from '@pilotiq/pilotiq/react'
+
+export default function ResourceForm() {
+  const ctx = usePageContext() as unknown as { viewProps?: Record<string, unknown>; data?: Record<string, unknown> }
+  const vp = (ctx.data ?? ctx.viewProps) as any ?? {}
+  return <SchemaRenderer elements={vp.schemaData ?? []} widgetData={vp._widgetData} />
+}
+`
+  writeIfChanged(path.join(outDir, 'resource-create', '+Page.tsx'), formPage)
+  writeIfChanged(path.join(outDir, 'resource-edit', '+Page.tsx'), formPage)
+
+  // ── Resource View — GET ${base}/${slug}/:id (3-segment, or
+  // 4-segment when cluster-prefixed). Yields to resource-create on
+  // 'create' and to the theme editor on 'theme'.
+  writeIfChanged(path.join(outDir, 'resource-view', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+import { clusterOffset } from '../_clusterOffset.js'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  const off = clusterOffset(parts)
+  if (parts.length !== 3 + off) return false
+  if (parts[2 + off] === 'create') return false
+  if (parts[1 + off] === 'theme')  return false
+  if (import.meta.env.SSR && !PilotiqRegistry.findByPath('/' + parts[0])) return false
+  return { routeParams: { basePath: parts[0], slug: parts[1 + off]!, id: parts[2 + off]! } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'resource-view', '+data.ts'), dataStub)
+  writeIfChanged(path.join(outDir, 'resource-view', '+Page.tsx'), formPage)
+
+  // NOTE: Custom pages are handled by the 'slug' route above (pageType: 'page')
+
+  // ── Plan #11 — Relation manager pages ────────────────────
+  // Four URL shapes mounted under a parent record:
+  //   list:    ${base}/${slug}/:id/${rel}                (4 parts)
+  //   create:  ${base}/${slug}/:id/${rel}/create         (5 parts, parts[4] === 'create')
+  //   view:    ${base}/${slug}/:id/${rel}/:childId       (5 parts, parts[4] !== 'create')
+  //   edit:    ${base}/${slug}/:id/${rel}/:childId/edit  (6 parts, parts[5] === 'edit')
+  //
+  // The reserved-token guard at boot in routes.ts ensures `${rel}` can
+  // never be 'edit' / 'delete' / '_form' / '_action' / '_search' /
+  // '_uploads' — so the segment-shape match here is unambiguous.
+  writeIfChanged(path.join(outDir, 'relation-list', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+import { clusterOffset } from '../_clusterOffset.js'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  const off = clusterOffset(parts)
+  if (parts.length !== 4 + off) return false
+  if (parts[3 + off] === 'edit') return false
+  if (import.meta.env.SSR && !PilotiqRegistry.findByPath('/' + parts[0])) return false
+  return { routeParams: { basePath: parts[0], slug: parts[1 + off]!, id: parts[2 + off]!, relationship: parts[3 + off]! } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'relation-list', '+data.ts'), dataStub)
+  writeIfChanged(path.join(outDir, 'relation-list', '+Page.tsx'), formPage)
+
+  writeIfChanged(path.join(outDir, 'relation-create', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+import { clusterOffset } from '../_clusterOffset.js'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  const off = clusterOffset(parts)
+  if (parts.length !== 5 + off || parts[4 + off] !== 'create') return false
+  if (import.meta.env.SSR && !PilotiqRegistry.findByPath('/' + parts[0])) return false
+  return { routeParams: { basePath: parts[0], slug: parts[1 + off]!, id: parts[2 + off]!, relationship: parts[3 + off]! } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'relation-create', '+data.ts'), dataStub)
+  writeIfChanged(path.join(outDir, 'relation-create', '+Page.tsx'), formPage)
+
+  writeIfChanged(path.join(outDir, 'relation-view', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+import { clusterOffset } from '../_clusterOffset.js'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  const off = clusterOffset(parts)
+  if (parts.length !== 5 + off) return false
+  if (parts[4 + off] === 'create') return false
+  if (import.meta.env.SSR && !PilotiqRegistry.findByPath('/' + parts[0])) return false
+  return { routeParams: { basePath: parts[0], slug: parts[1 + off]!, id: parts[2 + off]!, relationship: parts[3 + off]!, childId: parts[4 + off]! } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'relation-view', '+data.ts'), dataStub)
+  writeIfChanged(path.join(outDir, 'relation-view', '+Page.tsx'), formPage)
+
+  writeIfChanged(path.join(outDir, 'relation-edit', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+import { clusterOffset } from '../_clusterOffset.js'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  const off = clusterOffset(parts)
+  if (parts.length !== 6 + off || parts[5 + off] !== 'edit') return false
+  if (import.meta.env.SSR && !PilotiqRegistry.findByPath('/' + parts[0])) return false
+  return { routeParams: { basePath: parts[0], slug: parts[1 + off]!, id: parts[2 + off]!, relationship: parts[3 + off]!, childId: parts[4 + off]! } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'relation-edit', '+data.ts'), dataStub)
+  writeIfChanged(path.join(outDir, 'relation-edit', '+Page.tsx'), formPage)
+
+  // ── Phase B — Nested relation manager pages ──────────────
+  // Four URL shapes mounted under a per-record sub-resource:
+  //   nested-list:   ${base}/${slug}/:id/${rel}/:childId1/${rel2}              (6 parts)
+  //   nested-create: ${base}/${slug}/:id/${rel}/:childId1/${rel2}/create       (7 parts, parts[6]==='create')
+  //   nested-view:   ${base}/${slug}/:id/${rel}/:childId1/${rel2}/:childId2    (7 parts, parts[6]!=='create')
+  //   nested-edit:   ${base}/${slug}/:id/${rel}/:childId1/${rel2}/:childId2/edit (8 parts, parts[7]==='edit')
+  //
+  // 6-part disambiguation against `relation-edit` keys off `parts[5+off]`
+  // — relation-edit ends in `'edit'`, nested-list ends in `${rel2}`, and
+  // the reserved-token guard at boot ensures `${rel2}` is never literally
+  // `'edit'`. 7-part split between create / view mirrors the depth-1
+  // pattern exactly.
+  writeIfChanged(path.join(outDir, 'nested-relation-list', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+import { clusterOffset } from '../_clusterOffset.js'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  const off = clusterOffset(parts)
+  if (parts.length !== 6 + off) return false
+  if (parts[5 + off] === 'edit') return false
+  if (import.meta.env.SSR && !PilotiqRegistry.findByPath('/' + parts[0])) return false
+  return { routeParams: {
+    basePath:      parts[0],
+    slug:          parts[1 + off]!,
+    id:            parts[2 + off]!,
+    relationship:  parts[3 + off]!,
+    childId1:      parts[4 + off]!,
+    relationship2: parts[5 + off]!,
+  } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'nested-relation-list', '+data.ts'), dataStub)
+  writeIfChanged(path.join(outDir, 'nested-relation-list', '+Page.tsx'), formPage)
+
+  writeIfChanged(path.join(outDir, 'nested-relation-create', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+import { clusterOffset } from '../_clusterOffset.js'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  const off = clusterOffset(parts)
+  if (parts.length !== 7 + off || parts[6 + off] !== 'create') return false
+  if (import.meta.env.SSR && !PilotiqRegistry.findByPath('/' + parts[0])) return false
+  return { routeParams: {
+    basePath:      parts[0],
+    slug:          parts[1 + off]!,
+    id:            parts[2 + off]!,
+    relationship:  parts[3 + off]!,
+    childId1:      parts[4 + off]!,
+    relationship2: parts[5 + off]!,
+  } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'nested-relation-create', '+data.ts'), dataStub)
+  writeIfChanged(path.join(outDir, 'nested-relation-create', '+Page.tsx'), formPage)
+
+  writeIfChanged(path.join(outDir, 'nested-relation-view', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+import { clusterOffset } from '../_clusterOffset.js'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  const off = clusterOffset(parts)
+  if (parts.length !== 7 + off) return false
+  if (parts[6 + off] === 'create') return false
+  if (import.meta.env.SSR && !PilotiqRegistry.findByPath('/' + parts[0])) return false
+  return { routeParams: {
+    basePath:      parts[0],
+    slug:          parts[1 + off]!,
+    id:            parts[2 + off]!,
+    relationship:  parts[3 + off]!,
+    childId1:      parts[4 + off]!,
+    relationship2: parts[5 + off]!,
+    childId2:      parts[6 + off]!,
+  } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'nested-relation-view', '+data.ts'), dataStub)
+  writeIfChanged(path.join(outDir, 'nested-relation-view', '+Page.tsx'), formPage)
+
+  writeIfChanged(path.join(outDir, 'nested-relation-edit', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+import { clusterOffset } from '../_clusterOffset.js'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  const off = clusterOffset(parts)
+  if (parts.length !== 8 + off || parts[7 + off] !== 'edit') return false
+  if (import.meta.env.SSR && !PilotiqRegistry.findByPath('/' + parts[0])) return false
+  return { routeParams: {
+    basePath:      parts[0],
+    slug:          parts[1 + off]!,
+    id:            parts[2 + off]!,
+    relationship:  parts[3 + off]!,
+    childId1:      parts[4 + off]!,
+    relationship2: parts[5 + off]!,
+    childId2:      parts[6 + off]!,
+  } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'nested-relation-edit', '+data.ts'), dataStub)
+  writeIfChanged(path.join(outDir, 'nested-relation-edit', '+Page.tsx'), formPage)
+
+  // ── Theme Editor ─────────────────────────────────────────
+  writeIfChanged(path.join(outDir, 'theme', '+route.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import type { RouteSync } from 'vike/types'
+import { PilotiqRegistry } from '@pilotiq/pilotiq/registry'
+
+export const route: RouteSync = (pageContext) => {
+  const parts = pageContext.urlPathname.split('/').filter(Boolean)
+  if (parts.length !== 2 || parts[1] !== 'theme') return false
+  if (import.meta.env.SSR) {
+    const panel = PilotiqRegistry.findByPath('/' + parts[0])
+    if (!panel) return false
+    // Only match if themeEditor is enabled
+    if (!panel.getConfig().themeEditor) return false
+  }
+  return { routeParams: { basePath: parts[0] } }
+}
+`)
+  writeIfChanged(path.join(outDir, 'theme', '+data.ts'), dataStub)
+  writeIfChanged(path.join(outDir, 'theme', '+Page.tsx'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import { usePageContext } from 'vike-react/usePageContext'
+import { navigate } from 'vike/client/router'
+import { ThemeSettingsPage } from '@pilotiq/pilotiq/react'
+
+const handleNavigate = (url: string) => navigate(url, { overwriteLastHistoryEntry: true, scrollToTop: false } as any)
+
+export default function ThemeEditorPage() {
+  const ctx = usePageContext() as unknown as { viewProps?: Record<string, unknown>; data?: Record<string, unknown> }
+  const { basePath, themeConfig } = (ctx.data ?? ctx.viewProps) as any ?? {}
+  return <ThemeSettingsPage panelPath={basePath} initialConfig={themeConfig} onNavigate={handleNavigate} />
+}
+`)
+}
+
+/**
+ * Source-module info for the manifest. The plugin imports each panel
+ * module, finds the exported `Pilotiq` instances by name, and the
+ * client-side manifest re-imports those names + walks the runtime
+ * config to collect class refs at module init.
+ *
+ * No need to re-export every class from the panel module — they're
+ * reachable through the panel's `getConfig()` chain at runtime.
+ */
+interface PanelExport {
+  exportName: string
+  importPath: string
+}
+
+/**
+ * Resolve panel-path strings against the project root and import each.
+ * Returns the panels (Pilotiq instances) and the absolute resolved file
+ * path for each — needed so we can compute relative re-export paths.
+ */
+/**
+ * Discover Pilotiq-instance exports across the configured panel modules.
+ * Returns `{ exportName, importPath }` for each so the client-side
+ * manifest can re-import them by name.
+ */
+async function discoverPanelExports(
+  panelPaths: string[],
+  projectRoot: string,
+): Promise<PanelExport[]> {
+  // jiti gives us a Node-compatible loader that handles .ts/.tsx, ESM,
+  // and TypeScript syntax. `fsCache: false` + a fresh instance per
+  // call ensures HMR-style regeneration picks up edits.
+  const jiti = createJiti(projectRoot, { fsCache: false, moduleCache: false })
+  const out: PanelExport[] = []
+  for (const userPath of panelPaths) {
+    const resolved = await resolvePanelPath(userPath, projectRoot)
+    if (!resolved) continue
+    try {
+      const mod = await jiti.import(resolved) as Record<string, unknown>
+      for (const [name, value] of Object.entries(mod)) {
+        if (looksLikePilotiq(value)) out.push({ exportName: name, importPath: resolved })
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      throw new Error(
+        `[pilotiq vite plugin] Failed to import panel module "${userPath}" (resolved to "${resolved}"): ${msg}\n` +
+          `Panel files must be import-safe — top-level code must not run server-only logic.`,
+      )
+    }
+  }
+  return out
+}
+
+async function resolvePanelPath(userPath: string, projectRoot: string): Promise<string | null> {
+  const candidates = [userPath, userPath + '.ts', userPath + '.tsx', userPath + '.js', userPath + '.mjs']
+  for (const c of candidates) {
+    const abs = path.isAbsolute(c) ? c : path.resolve(projectRoot, c)
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) return abs
+  }
+  return null
+}
+
+function looksLikePilotiq(value: unknown): boolean {
+  if (!value || typeof value !== 'object') return false
+  const v = value as { getConfig?: unknown }
+  return typeof v.getConfig === 'function'
+}
+
+/**
+ * Write the component manifest. The manifest imports the user's
+ * `Pilotiq` instances by name, walks their `getConfig()`, and stamps
+ * every Resource/Global/Page class into a `componentRegistry` object
+ * keyed by class name. Classes are reached through the panel's runtime
+ * config, so the user doesn't need to re-export them from the panel
+ * module.
+ */
+function writeComponentsManifest(panelExports: PanelExport[], pagesRoot: string): void {
+  const outDir = path.join(pagesRoot, '(pilotiq)')
+  fs.mkdirSync(outDir, { recursive: true })
+
+  writeIfChanged(path.join(outDir, '_clusterOffset.ts'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import { clusterSlugsByBasePath } from './_components.js'
+
+export function clusterOffset(parts: string[]): number {
+  if (parts.length < 2) return 0
+  const slugs = clusterSlugsByBasePath['/' + parts[0]]
+  return slugs && slugs.includes(parts[1]) ? 1 : 0
+}
+`)
+
+  const lines = [
+    '// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.',
+    '// Imports each registered Pilotiq instance and walks its config to',
+    '// expose every Resource/Global/Page class as `componentRegistry[ClassName]`.',
+    '// The renderer uses this to resolve component-typed icons.',
+    '',
+  ]
+
+  if (panelExports.length === 0) {
+    lines.push('// (no panels found — register classes via Pilotiq.make() in your panel module)')
+    lines.push('export const componentRegistry: Record<string, unknown> = {}')
+    lines.push('export const clusterSlugsByBasePath: Record<string, string[]> = {}')
+    lines.push('export const rightPanelRegistry: Record<string, unknown> = {}')
+    lines.push('')
+    writeIfChanged(path.join(outDir, '_components.ts'), lines.join('\n'))
+    return
+  }
+
+  // Group exports by source path so we emit one import per file.
+  const byPath = new Map<string, string[]>()
+  for (const e of panelExports) {
+    if (!byPath.has(e.importPath)) byPath.set(e.importPath, [])
+    byPath.get(e.importPath)!.push(e.exportName)
+  }
+  for (const [absPath, names] of byPath) {
+    let rel = path.relative(outDir, absPath).replace(/\\/g, '/')
+    if (!rel.startsWith('.')) rel = './' + rel
+    rel = rel.replace(/\.tsx?$/, '').replace(/\.jsx?$/, '')
+    lines.push(`import { ${names.join(', ')} } from '${rel}'`)
+  }
+
+  const allExportNames = panelExports.map(e => e.exportName).join(', ')
+  lines.push('')
+  lines.push('const _all: Record<string, unknown> = {}')
+  lines.push('const _clusters: Record<string, string[]> = {}')
+  lines.push('const _rightPanels: Record<string, unknown> = {}')
+  lines.push('function _add(c: any) { if (typeof c === \'function\' && c.name) _all[c.name] = c }')
+  lines.push('function _walk(p: any) {')
+  lines.push('  const cfg = p?.getConfig?.()')
+  lines.push('  cfg?.resources?.forEach(_add)')
+  lines.push('  cfg?.globals?.forEach(_add)')
+  lines.push('  cfg?.pages?.forEach(_add)')
+  lines.push('  if (Array.isArray(cfg?.rightPanels)) {')
+  lines.push('    for (const _c of cfg.rightPanels) {')
+  lines.push('      if (_c && typeof _c.id === \'string\' && _c.render) _rightPanels[_c.id] = _c.render')
+  lines.push('    }')
+  lines.push('  }')
+  lines.push('  if (cfg?.path && Array.isArray(cfg?.clusters)) {')
+  lines.push('    const slugs = cfg.clusters.map((C: any) => (typeof C?.getSlug === \'function\' ? C.getSlug() : \'\')).filter(Boolean)')
+  lines.push('    if (slugs.length > 0) _clusters[cfg.path] = slugs')
+  lines.push('  }')
+  lines.push('}')
+  lines.push(`for (const _p of [${allExportNames}]) _walk(_p)`)
+  lines.push('')
+  lines.push('export const componentRegistry: Record<string, unknown> = _all')
+  lines.push('export const clusterSlugsByBasePath: Record<string, string[]> = _clusters')
+  lines.push('export const rightPanelRegistry: Record<string, unknown> = _rightPanels')
+  lines.push('')
+
+  writeIfChanged(path.join(outDir, '_components.ts'), lines.join('\n'))
+}
+
+/**
+ * Update the auto-gen `+Layout.tsx` template to import the manifest and
+ * pass it to `AppShell`. Idempotent — overwrites on each run.
+ */
+function writeLayoutWithManifest(pagesRoot: string): void {
+  const outDir = path.join(pagesRoot, '(pilotiq)')
+  writeIfChanged(path.join(outDir, '+Layout.tsx'), `// AUTO-GENERATED by @pilotiq/pilotiq — do not edit.
+import { usePageContext } from 'vike-react/usePageContext'
+import { AppShell, ThemeProvider, generateThemeCSS, NavigateProvider } from '@pilotiq/pilotiq/react'
+import { navigate as vikeNavigate } from 'vike/client/router'
+import { componentRegistry, rightPanelRegistry } from './_components.js'
+import type { ReactNode } from 'react'
+
+// Wrap vike's async navigate so the NavigateProvider's fire-and-forget
+// signature is satisfied. \`scrollToTop: false\` keeps the user's scroll
+// position across SPA-only updates (filter changes, sort, pagination).
+const navigate = (url: string): void => {
+  void vikeNavigate(url, { scrollToTop: false } as any)
+}
+
+export default function PilotiqLayout({ children }: { children: ReactNode }) {
+  const ctx = usePageContext() as unknown as { viewProps?: Record<string, unknown>; data?: Record<string, unknown>; urlPathname?: string }
+  const { panel, basePath, layout, notifications } = (ctx.data ?? ctx.viewProps) as any ?? {}
+  const currentPath = ctx.urlPathname
+  if (!panel) return <NavigateProvider navigate={navigate}>{children}</NavigateProvider>
+
+  // SSR: inject theme CSS inline to prevent FOUC
+  const themeCss = panel.theme ? generateThemeCSS(panel.theme) : null
+
+  return (
+    <NavigateProvider navigate={navigate}>
+      <ThemeProvider theme={panel.theme}>
+        {themeCss && <style dangerouslySetInnerHTML={{ __html: themeCss }} />}
+        <AppShell panel={panel} basePath={basePath} layout={layout} notifications={notifications} currentPath={currentPath} componentRegistry={componentRegistry as any} rightPanelRegistry={rightPanelRegistry as any}>
+          {children}
+        </AppShell>
+      </ThemeProvider>
+    </NavigateProvider>
+  )
+}
+`)
+}
+
+const DEFAULT_PANEL_PATHS = ['./app/Pilotiq/AdminPanel']
+
+export function pilotiq(options: PilotiqVitePluginOptions = {}): Plugin {
+  const cwd = process.cwd()
+  const pagesRoot = path.join(cwd, 'pages')
+  const panelPaths = options.panels === undefined
+    ? DEFAULT_PANEL_PATHS
+    : Array.isArray(options.panels) ? options.panels : [options.panels]
+
+  // Generate at construction time — before Vike scans pages/.
+  // The component manifest is regenerated lazily inside buildStart /
+  // configureServer because importing user code requires Vite's
+  // module-resolution context.
+  generatePages(pagesRoot)
+  // Emit a stub manifest so the auto-gen +Layout.tsx import resolves
+  // even before buildStart runs.
+  writeComponentsManifest([], pagesRoot)
+  writeLayoutWithManifest(pagesRoot)
+
+  const regenerateManifest = async (): Promise<void> => {
+    const exports = await discoverPanelExports(panelPaths, cwd)
+    writeComponentsManifest(exports, pagesRoot)
+  }
+
+  return {
+    name: 'pilotiq:pages',
+    enforce: 'pre',
+    async buildStart() {
+      generatePages(pagesRoot)
+      writeLayoutWithManifest(pagesRoot)
+      try {
+        await regenerateManifest()
+      } catch (err) {
+        // Surface as a Vite build error
+        this.error(err instanceof Error ? err.message : String(err))
+      }
+    },
+    configureServer(devServer) {
+      // Watch panel files so editing AdminPanel.ts regenerates the
+      // manifest in dev. Best-effort: regenerate on any FS event.
+      const watch = async () => {
+        try { await regenerateManifest() } catch {}
+      }
+      const watcher = devServer.watcher
+      for (const userPath of panelPaths) {
+        const guess = path.isAbsolute(userPath) ? userPath : path.resolve(cwd, userPath)
+        watcher.add(guess + '.ts')
+        watcher.add(guess + '.tsx')
+      }
+      watcher.on('change', watch)
+      watcher.on('add', watch)
+      watcher.on('unlink', watch)
+    },
+  }
+}