@pilotiq/pilotiq 0.21.0 → 0.23.0

package/src/Pilotiq.ts

@@ -6,6 +6,7 @@ import type { ClusterClass } from './Cluster.js'
 import type { Page } from './Page.js'
 import type { SchemaDefinition } from './schema/resolveSchema.js'
 import type { ThemeConfig } from './theme/types.js'
+import type { ThemeStorageAdapter } from './theme/storage.js'
 import type { UploadAdapter } from './uploads/UploadAdapter.js'
 import type { UserMenuItem } from './UserMenuItem.js'
 import type { NavigationBadgeColor } from './Resource.js'
@@ -228,6 +229,16 @@ export interface PilotiqConfig {
   profilePage?: typeof Page
   theme?:        ThemeConfig
   themeEditor?:  boolean
+  /**
+   * Theme override persistence adapter — wired via
+   * `themeEditor({ storage })`. Reads/writes the JSON blob the editor
+   * page produces. Without this, the service provider falls back to
+   * the implicit Prisma adapter (auto-resolved via
+   * `app.make('prisma')`) for back-compat — that fallback is
+   * deprecated and will be removed in a future minor; pass `storage`
+   * explicitly.
+   */
+  themeStorage?: ThemeStorageAdapter
   guard?:        (req: unknown) => boolean | Promise<boolean>
   user?:         UserResolver
   uploads?:      UploadConfig
@@ -317,6 +328,11 @@ export interface PilotiqConfig {
   aiSuggestionsMode?: 'auto' | 'review'
   /** @internal Runtime theme overrides from DB. */
   _themeOverrides?: Partial<ThemeConfig>
+  /**
+   * TTL (milliseconds) for the per-user navigation badge cache. Set to
+   * `0` (or `null` via the builder) to disable caching. Default 30000.
+   */
+  navigationBadgeTtlMs?: number
 }
 
 /**
@@ -369,6 +385,21 @@ export interface ComponentSlots {
 export class Pilotiq {
   private config: PilotiqConfig
   private installedPlugins: PilotiqPlugin[] = []
+  /** Lazy slug-indexed caches. Built on first lookup; invalidated when
+   *  the underlying setter mutates the matching array. Resources /
+   *  globals / pages are looked up by slug 16+ times per request across
+   *  the page-data builders — the linear `Array.find` adds up around 50+
+   *  resources. */
+  private _resourceBySlug?: Map<string, ResourceClass>
+  private _globalBySlug?:   Map<string, GlobalClass>
+  private _pageBySlug?:     Map<string, typeof Page>
+  /**
+   * Per-user navigation badge cache. Keyed by `${ownerName}|${userKey}`
+   * — `userKey` derived from `user.id` (or the primitive user / JSON
+   * fallback / `''` for anon). Each entry expires after
+   * `getNavigationBadgeTtl()` ms.
+   */
+  private _navigationBadgeCache: Map<string, { value: string | undefined; expires: number }> = new Map()
 
   private constructor(name: string) {
     this.config = {
@@ -399,16 +430,19 @@ export class Pilotiq {
 
   resources(r: ResourceClass[]): this {
     this.config.resources = r
+    delete this._resourceBySlug
     return this
   }
 
   globals(g: GlobalClass[]): this {
     this.config.globals = g
+    delete this._globalBySlug
     return this
   }
 
   pages(p: (typeof Page)[]): this {
     this.config.pages = p
+    delete this._pageBySlug
     return this
   }
 
@@ -453,6 +487,7 @@ export class Pilotiq {
     this.config.dashboardPage = P
     if (!this.config.pages.includes(P)) {
       this.config.pages = [...this.config.pages, P]
+      delete this._pageBySlug
     }
     return this
   }
@@ -476,6 +511,7 @@ export class Pilotiq {
     this.config.profilePage = P
     if (!this.config.pages.includes(P)) {
       this.config.pages = [...this.config.pages, P]
+      delete this._pageBySlug
     }
     return this
   }
@@ -961,6 +997,24 @@ export class Pilotiq {
     this.config.themeEditor = true
   }
 
+  /** @internal — assign the storage adapter resolved by the
+   *  `themeEditor({ storage })` plugin OR by the service provider's
+   *  back-compat Prisma fallback. Both writers funnel through this
+   *  setter so the route handlers consume a single slot. */
+  _setThemeStorage(adapter: ThemeStorageAdapter | undefined): void {
+    if (adapter === undefined) {
+      delete this.config.themeStorage
+    } else {
+      this.config.themeStorage = adapter
+    }
+  }
+
+  /** @internal — the active theme storage adapter (explicit or the
+   *  boot-time Prisma fallback). Routes read from here. */
+  getThemeStorage(): ThemeStorageAdapter | undefined {
+    return this.config.themeStorage
+  }
+
   /** @internal */
   setThemeOverrides(overrides: Partial<ThemeConfig> | undefined): void {
     if (overrides === undefined) {
@@ -980,6 +1034,93 @@ export class Pilotiq {
     return { ...base, ...overrides }
   }
 
+  /**
+   * Slug-indexed lookup for resources. O(1) replacement for
+   * `cfg.resources.find(r => r.getSlug() === slug)`. Built lazily on
+   * first call; invalidated when `.resources([…])` is reassigned.
+   */
+  findResource(slug: string): ResourceClass | undefined {
+    if (!this._resourceBySlug) {
+      this._resourceBySlug = new Map(this.config.resources.map(r => [r.getSlug(), r]))
+    }
+    return this._resourceBySlug.get(slug)
+  }
+
+  /** Slug-indexed lookup for globals. See `findResource`. */
+  findGlobal(slug: string): GlobalClass | undefined {
+    if (!this._globalBySlug) {
+      this._globalBySlug = new Map(this.config.globals.map(g => [g.getSlug(), g]))
+    }
+    return this._globalBySlug.get(slug)
+  }
+
+  /** Slug-indexed lookup for pages. See `findResource`. */
+  findPage(slug: string): typeof Page | undefined {
+    if (!this._pageBySlug) {
+      this._pageBySlug = new Map(this.config.pages.map(p => [p.getSlug(), p]))
+    }
+    return this._pageBySlug.get(slug)
+  }
+
+  /**
+   * TTL (milliseconds) for the per-user navigation badge cache. Badges
+   * resolve once per `(owner, userIdentity)` pair and serve from the
+   * in-memory cache until the TTL elapses; the cache covers the
+   * common case where a panel with N resources each running
+   * `Model.count()` for a sidebar badge would otherwise issue N queries
+   * on every page nav.
+   *
+   * Pass `0` (or `null`) to disable caching entirely. Default 30000.
+   */
+  navigationBadgeTtl(ms: number | null): this {
+    if (ms === null) {
+      delete this.config.navigationBadgeTtlMs
+    } else {
+      this.config.navigationBadgeTtlMs = Math.max(0, ms)
+    }
+    // Bust on reconfigure so the new TTL doesn't reuse stale slots.
+    this._navigationBadgeCache.clear()
+    return this
+  }
+
+  /** @internal — resolved TTL in milliseconds. Default 30s. `0`
+   *  disables caching (each request re-resolves). */
+  getNavigationBadgeTtl(): number {
+    return this.config.navigationBadgeTtlMs ?? 30_000
+  }
+
+  /** @internal — cache key for one (owner, user) pair. */
+  navigationBadgeCacheKey(ownerName: string, user: unknown): string {
+    return `${ownerName}|${userIdentityKey(user)}`
+  }
+
+  /** @internal — read-through cache for a single owner's badge value.
+   *  Caller supplies the resolver; cache wraps it with the configured
+   *  TTL. When TTL is 0 the resolver is invoked unconditionally and
+   *  nothing is stored. */
+  async resolveNavigationBadge(
+    ownerName: string,
+    user:      unknown,
+    resolver:  () => Promise<string | undefined>,
+  ): Promise<string | undefined> {
+    const ttl = this.getNavigationBadgeTtl()
+    if (ttl <= 0) return resolver()
+
+    const key = this.navigationBadgeCacheKey(ownerName, user)
+    const now = Date.now()
+    const hit = this._navigationBadgeCache.get(key)
+    if (hit && hit.expires > now) return hit.value
+
+    const value = await resolver()
+    this._navigationBadgeCache.set(key, { value, expires: now + ttl })
+    return value
+  }
+
+  /** @internal — test seam; clears the per-user badge cache. */
+  _clearNavigationBadgeCache(): void {
+    this._navigationBadgeCache.clear()
+  }
+
   /** @internal */
   getConfig(): Readonly<PilotiqConfig> {
     return this.config
@@ -990,3 +1131,28 @@ export class Pilotiq {
     return this.installedPlugins
   }
 }
+
+/**
+ * Stable cache key derived from a user object. Pilotiq treats the user
+ * as opaque, so we sniff the common shapes:
+ *
+ * 1. `null` / `undefined` — anonymous request; everyone shares one slot.
+ * 2. Primitive (string / number / bigint / boolean) — stringify directly.
+ * 3. Object with `id` — `String(user.id)` (the 99% case for app-supplied users).
+ * 4. Other objects — `JSON.stringify` as a last resort; falls back to a
+ *    sentinel if stringify throws (cycles).
+ *
+ * Two distinct users with the same `id` collide, but that's the same
+ * collision the rest of the framework already trusts.
+ */
+function userIdentityKey(user: unknown): string {
+  if (user === null || user === undefined) return ''
+  const t = typeof user
+  if (t === 'string' || t === 'number' || t === 'bigint' || t === 'boolean') return String(user)
+  if (t === 'object') {
+    const u = user as { id?: unknown }
+    if (u.id !== undefined && u.id !== null) return String(u.id)
+    try { return JSON.stringify(user) } catch { return '__opaque__' }
+  }
+  return '__opaque__'
+}

package/src/PilotiqServiceProvider.ts

@@ -3,9 +3,14 @@ import type { Application } from '@rudderjs/core'
 import type { Pilotiq } from './Pilotiq.js'
 import { PilotiqRegistry } from './PilotiqRegistry.js'
 import { registerPilotiqRoutes } from './routes.js'
+import { migrateThemeOverrides } from './theme/migrate.js'
+import { prismaThemeStorage } from './theme/storage.js'
+import type { PanelGlobalDelegate, ThemeStorageAdapter } from './theme/storage.js'
 
 // ─── Service Provider ─────────────────────────────────────
 
+const autoFallbackWarned = new Set<string>()
+
 class PilotiqServiceProvider extends ServiceProvider {
   private panels: Pilotiq[]
 
@@ -26,25 +31,72 @@ class PilotiqServiceProvider extends ServiceProvider {
       router: Parameters<typeof registerPilotiqRoutes>[0]
     }
 
-    // Load saved theme overrides from DB for panels with themeEditor enabled
     for (const panel of PilotiqRegistry.all()) {
       if (panel.getConfig().themeEditor) {
-        try {
-          const prisma = this.app.make('prisma') as any
-          const slug = `${panel.getConfig().name}__theme`
-          const row = await prisma.panelGlobal.findUnique({ where: { slug } })
-          if (row?.data) {
-            const raw = typeof row.data === 'string' ? JSON.parse(row.data as string) : row.data
-            const { migrateThemeOverrides } = await import('./theme/migrate.js')
-            panel.setThemeOverrides(migrateThemeOverrides(raw))
-          }
-        } catch { /* no DB or no table — use code defaults */ }
+        await loadThemeOverrides(this.app, panel)
       }
       registerPilotiqRoutes(router, panel)
     }
   }
 }
 
+/**
+ * Resolve the panel's theme storage adapter and hydrate any persisted
+ * overrides onto the panel.
+ *
+ * - Explicit `themeEditor({ storage })`: errors bubble (the user opted
+ *   in, misconfiguration should surface loudly).
+ * - Implicit Prisma fallback: errors swallowed for back-compat with a
+ *   one-time deprecation warning. Removing this branch is the breaking
+ *   change scheduled for the next minor.
+ */
+async function loadThemeOverrides(app: Application, panel: Pilotiq): Promise<void> {
+  const adapter = resolveThemeStorage(app, panel)
+  if (!adapter) return
+
+  const isExplicit = panel.getConfig().themeStorage === adapter
+  if (!isExplicit) panel._setThemeStorage(adapter)
+
+  try {
+    const overrides = await adapter.load()
+    if (overrides) panel.setThemeOverrides(migrateThemeOverrides(overrides))
+  } catch (e) {
+    if (isExplicit) throw e
+    // Implicit fallback: swallow connection / schema errors. Removed
+    // alongside the auto-fallback branch in a future minor.
+  }
+}
+
+function resolveThemeStorage(app: Application, panel: Pilotiq): ThemeStorageAdapter | null {
+  const explicit = panel.getConfig().themeStorage
+  if (explicit) return explicit
+
+  let prisma: PanelGlobalDelegate | null
+  try {
+    prisma = app.make('prisma') as PanelGlobalDelegate
+  } catch {
+    return null
+  }
+  if (!prisma || typeof prisma.panelGlobal?.findUnique !== 'function') return null
+
+  const panelName = panel.getConfig().name
+  if (!autoFallbackWarned.has(panelName)) {
+    autoFallbackWarned.add(panelName)
+    console.warn(
+      `[pilotiq] themeEditor() on panel "${panelName}" is using the implicit ` +
+      `Prisma fallback for theme persistence. Pass storage explicitly — ` +
+      `themeEditor({ storage: prismaThemeStorage(prisma, { slug: '${panelName}__theme' }) }) — ` +
+      `the implicit fallback is deprecated and will be removed in a future minor.`,
+    )
+  }
+  return prismaThemeStorage(prisma, { slug: `${panelName}__theme` })
+}
+
+/** @internal — test seam; resets the "deprecation already warned" memo. */
+export function _resetThemeFallbackWarned(): void {
+  autoFallbackWarned.clear()
+}
+
 // ─── Factory ──────────────────────────────────────────────
 
 /**

package/src/actions/importFactory.ts

@@ -65,6 +65,11 @@ export interface ImportOptions {
    *  exceeded — protects against accidental million-row uploads. Default
    *  `10_000`. */
   maxRows?: number
+  /** Number of rows to process in parallel. The importer chunks the row
+   *  list into batches of this size and runs each chunk via `Promise.all`.
+   *  Order within a chunk is non-deterministic; row indices in error
+   *  messages still match the original CSV/JSON position. Default `10`. */
+  concurrency?: number
   /** Final hook after the import loop. Useful for audit-log writes,
    *  cache invalidation, etc. Async-aware. */
   onComplete?: (summary: ImportSummary, ctx: ImportContext) => void | Promise<void>
@@ -123,16 +128,21 @@ export async function runImport(
 ): Promise<ImportSummary> {
   const summary: ImportSummary = { created: 0, updated: 0, skipped: 0, errors: [] }
   const upsertBy = opts.upsertBy
+  const concurrency = Math.max(1, opts.concurrency ?? 10)
 
-  for (let i = 0; i < rows.length; i++) {
-    const row = rows[i]!
+  // Per-row outcome — a small value type so chunks can resolve in any
+  // order and we still accumulate `summary` in original-row order.
+  type RowOutcome =
+    | { kind: 'created' }
+    | { kind: 'updated' }
+    | { kind: 'skipped'; row: number; message: string }
+
+  async function processRow(row: Record<string, unknown>, i: number): Promise<RowOutcome> {
     const rowCtx: ImportContext = { ...ctx, rowIndex: i }
     try {
       const guard = await opts.validate?.(row, rowCtx)
       if (typeof guard === 'string' && guard.length > 0) {
-        summary.skipped++
-        summary.errors.push({ row: i + 1, message: guard })
-        continue
+        return { kind: 'skipped', row: i + 1, message: guard }
       }
 
       if (mode === 'upsert' && upsertBy) {
@@ -144,8 +154,7 @@ export async function runImport(
             ? await opts.beforeUpdate(row, existing, rowCtx)
             : row
           await M.update(id, payload)
-          summary.updated++
-          continue
+          return { kind: 'updated' }
         }
       }
 
@@ -153,10 +162,22 @@ export async function runImport(
         ? await opts.beforeCreate(row, rowCtx)
         : row
       await M.create(payload)
-      summary.created++
+      return { kind: 'created' }
     } catch (err) {
-      summary.skipped++
-      summary.errors.push({ row: i + 1, message: err instanceof Error ? err.message : 'unknown' })
+      return { kind: 'skipped', row: i + 1, message: err instanceof Error ? err.message : 'unknown' }
+    }
+  }
+
+  for (let start = 0; start < rows.length; start += concurrency) {
+    const slice = rows.slice(start, start + concurrency)
+    const outcomes = await Promise.all(slice.map((row, idx) => processRow(row, start + idx)))
+    for (const outcome of outcomes) {
+      if (outcome.kind === 'created')      summary.created++
+      else if (outcome.kind === 'updated') summary.updated++
+      else {
+        summary.skipped++
+        summary.errors.push({ row: outcome.row, message: outcome.message })
+      }
     }
   }
 

package/src/orm/modelDefaults.ts

@@ -50,6 +50,16 @@ export interface ModelQuery {
   orderBy(column: string, direction?: 'ASC' | 'DESC'): ModelQuery
   paginate(page: number, perPage?: number): Promise<{ data: unknown[]; total: number }>
 
+  /**
+   * Single-row `LIMIT 1` SELECT — Laravel-parity sibling of `paginate`
+   * for the "first matching row" case. Optional on the structural shape;
+   * the `@rudderjs/orm` `QueryBuilder` ships it, test stubs typically
+   * don't. Callers that need it should fall back to
+   * `(await q.paginate(1, 1)).data[0]` when absent — see `findRecord` /
+   * `loadSingularRecord` / `childBelongsToParent` for the pattern.
+   */
+  first?(): Promise<unknown | null>
+
   /**
    * Plan #13 — soft-delete query scopes. Optional on the structural
    * shape; the `@rudderjs/orm-prisma` QueryBuilder ships them when
@@ -192,7 +202,7 @@ export function modelLoadRecord(R: ResourceLike): LoadRecordHandler {
  * `Global` subclasses with `static model = M` set get this wired
  * automatically by `defaultGlobalEditPage`.
  *
- * Default strategy: paginate(1, 1) — i.e. "the first row". Pass
+ * Default strategy: `.first()` — i.e. the first matching row. Pass
  * `findSingular` to switch to a fixed-id lookup
  * (`(q) => q.where('id', '=', 1)`) or a slug-style lookup
  * (`(q) => q.where('key', '=', 'site')`).
@@ -208,6 +218,7 @@ export function loadSingularRecord(
   return async (): Promise<unknown> => {
     let q = M.query()
     if (opts?.findSingular) q = opts.findSingular(q)
+    if (q.first) return (await q.first()) ?? null
     const result = await q.paginate(1, 1)
     const data = (result?.data ?? []) as unknown[]
     return data[0] ?? null
@@ -234,7 +245,9 @@ export async function findRecord<T = unknown>(
   const M = R.model
   if (!M) return undefined
   const pk = getPrimaryKey(M)
-  const result = await R.query(ctx).where(pk, '=', id).paginate(1, 1)
+  const q = R.query(ctx).where(pk, '=', id)
+  if (q.first) return ((await q.first()) ?? undefined) as T | undefined
+  const result = await q.paginate(1, 1)
   const data = (result?.data ?? []) as unknown[]
   return data[0] as T | undefined
 }

package/src/pageData/forms.ts

@@ -58,7 +58,7 @@ async function resolveScopeForm(
   let baseCtxExtras: Record<string, unknown> = {}
 
   if (scope.kind === 'resource-create' || scope.kind === 'resource-edit') {
-    const R = cfg.resources.find(r => r.getSlug() === scope.slug)
+    const R = pilotiq.findResource(scope.slug)
     if (!R) return null
     const pages = R.resolvePages()
     if (scope.kind === 'resource-create') {
@@ -77,14 +77,14 @@ async function resolveScopeForm(
       }
     }
   } else if (scope.kind === 'global-edit') {
-    const G = cfg.globals.find(g => g.getSlug() === scope.slug)
+    const G = pilotiq.findGlobal(scope.slug)
     if (!G) return null
     const pages = G.resolvePages()
     if (!pages.edit) return null
     PageClass = pages.edit
     mode = 'edit'
   } else {
-    const P = cfg.pages.find(p => p.getSlug() === scope.pageSlug)
+    const P = pilotiq.findPage(scope.pageSlug)
     if (!P) return null
     PageClass = P
     // Custom pages don't have a record/edit-mode concept — pass mode

package/src/pageData/misc.ts

@@ -43,7 +43,7 @@ export async function globalEditData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const G = cfg.globals.find(g => g.getSlug() === slug)
+  const G = pilotiq.findGlobal(slug)
   if (!G) return null
   const pages = G.resolvePages()
   if (!pages.edit) return null
@@ -98,7 +98,7 @@ export async function globalViewData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const G = cfg.globals.find(g => g.getSlug() === slug)
+  const G = pilotiq.findGlobal(slug)
   if (!G) return null
   const pages = G.resolvePages()
   if (!pages.view) return null
@@ -134,7 +134,7 @@ export async function customPageData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const PageClass = cfg.pages.find(P => P.getSlug() === pageSlug)
+  const PageClass = pilotiq.findPage(pageSlug)
   if (!PageClass) return null
 
   const pageUrl = pageBasePath(cfg.path, PageClass)
@@ -237,14 +237,14 @@ export async function widgetData(
     ctx = uploadCtx(userCtx({ basePath: cfg.path }, user), cfg)
     elements = await callPageSchema(cfg.dashboardPage, ctx)
   } else if (scope.kind === 'page') {
-    const P = cfg.pages.find(p => p.getSlug() === scope.pageSlug)
+    const P = pilotiq.findPage(scope.pageSlug)
     if (!P) return { ok: false, status: 404, error: 'Page not found' }
     ctx = uploadCtx(userCtx({ basePath: cfg.path }, user), cfg)
     elements = await callPageSchema(P, ctx)
   } else {
     // Resource-scope: re-resolve the list page's schema so widgets from
     // `Resource.headerSchema()` / `footerSchema()` are reachable.
-    const R = cfg.resources.find(r => r.getSlug() === scope.slug)
+    const R = pilotiq.findResource(scope.slug)
     if (!R) return { ok: false, status: 404, error: 'Resource not found' }
     const pages = R.resolvePages()
     if (!pages.index) return { ok: false, status: 404, error: 'Resource has no list page' }

package/src/pageData/navigation.ts

@@ -627,7 +627,7 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
   const raw: RawNavItem[] = []
   let idx = 0
 
-  const pushBadge: Array<{ item: RawNavItem; handler: () => unknown }> = []
+  const pushBadge: Array<{ item: RawNavItem; handler: () => unknown; owner: string }> = []
 
   // Plan #10 — pre-evaluate canAccess for every owner in parallel so we
   // can drop forbidden items before flattening. Failed predicates fail
@@ -672,7 +672,7 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
     if (R.cluster)                              item.parent       = R.cluster.name
     else if (R.navigationParentItem !== undefined) item.parent    = R.navigationParentItem
     if (R.navigationBadgeColor   !== 'default') item.badgeColor   = R.navigationBadgeColor
-    if (R.navigationBadge)                       pushBadge.push({ item, handler: R.navigationBadge })
+    if (R.navigationBadge)                       pushBadge.push({ item, handler: R.navigationBadge, owner: R.name })
     raw.push(item)
   }
 
@@ -697,7 +697,7 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
     if (G.cluster)                              item.parent       = G.cluster.name
     else if (G.navigationParentItem !== undefined) item.parent    = G.navigationParentItem
     if (G.navigationBadgeColor   !== 'default') item.badgeColor   = G.navigationBadgeColor
-    if (G.navigationBadge)                       pushBadge.push({ item, handler: G.navigationBadge })
+    if (G.navigationBadge)                       pushBadge.push({ item, handler: G.navigationBadge, owner: G.name })
     raw.push(item)
   }
 
@@ -724,7 +724,7 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
     if (P.cluster && !isDashboard)              item.parent       = P.cluster.name
     else if (P.navigationParentItem !== undefined) item.parent    = P.navigationParentItem
     if (P.navigationBadgeColor   !== 'default') item.badgeColor   = P.navigationBadgeColor
-    if (P.navigationBadge)                       pushBadge.push({ item, handler: P.navigationBadge })
+    if (P.navigationBadge)                       pushBadge.push({ item, handler: P.navigationBadge, owner: P.name })
     raw.push(item)
   }
 
@@ -755,15 +755,17 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
     if (C.navigationSort         !== undefined) item.sort         = C.navigationSort
     if (C.navigationParentItem   !== undefined) item.parent       = C.navigationParentItem
     if (C.navigationBadgeColor   !== 'default') item.badgeColor   = C.navigationBadgeColor
-    if (C.navigationBadge)                       pushBadge.push({ item, handler: C.navigationBadge })
+    if (C.navigationBadge)                       pushBadge.push({ item, handler: C.navigationBadge, owner: C.name })
     raw.push(item)
   }
 
-  await Promise.all(pushBadge.map(async ({ item, handler }) => {
+  await Promise.all(pushBadge.map(async ({ item, handler, owner }) => {
     try {
-      const v = await handler()
-      if (v === undefined || v === null) return
-      item.badge = String(v)
+      const v = await pilotiq.resolveNavigationBadge(owner, user, async () => {
+        const raw = await handler()
+        return raw === undefined || raw === null ? undefined : String(raw)
+      })
+      if (v !== undefined) item.badge = v
     } catch {
       // Per-badge errors stay silent.
     }

package/src/pageData/relationPages.ts

@@ -193,7 +193,9 @@ async function childBelongsToParent(
     const q: ModelQuery = (parentModel.relatedQuery
       ? parentModel.relatedQuery(parent, relationship)
       : (parent as { related: (n: string) => ModelQuery }).related(relationship))
-    const result = await q.where(childPk, '=', childId).paginate(1, 1)
+      .where(childPk, '=', childId)
+    if (q.first) return (await q.first()) !== null
+    const result = await q.paginate(1, 1)
     return result.total > 0
   } catch {
     return false
@@ -294,7 +296,7 @@ export async function relationManagerData(
 
   const cfg = pilotiq.getConfig()
 
-  const R = cfg.resources.find(r => r.getSlug() === scope.slug)
+  const R = pilotiq.findResource(scope.slug)
   if (!R) return null
 
   const M = findManager(R, scope.relationship)
@@ -769,7 +771,7 @@ export async function resolveRelationChain(
 ): Promise<ResolvedChain | { ok: false; status: 403 } | null> {
   const cfg = pilotiq.getConfig()
 
-  const R = cfg.resources.find(r => r.getSlug() === scope.slug)
+  const R = pilotiq.findResource(scope.slug)
   if (!R) return null
 
   // Layer 0 — same gates as the depth-1 pipeline.

package/src/pageData/resourcePages.ts

@@ -142,7 +142,7 @@ export async function resourceIndexData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
 
   const pages = R.resolvePages()
@@ -193,7 +193,7 @@ export async function resourceTableData(
   req?:    unknown,
 ): Promise<{ tables: Record<string, unknown>[] } | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
 
   const pages = R.resolvePages()
@@ -321,7 +321,7 @@ export async function resourceCreateData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
   const pages = R.resolvePages()
   if (!pages.create) return null
@@ -373,7 +373,7 @@ export async function resourceEditData(
   req?:     unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
   const pages = R.resolvePages()
   if (!pages.edit) return null
@@ -466,7 +466,7 @@ export async function resourceViewData(
   req?:     unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
   const pages = R.resolvePages()
   if (!pages.view) return null
@@ -538,7 +538,7 @@ export async function resourceRecordPageData(
   req?:          unknown,
 ): Promise<Record<string, unknown> | null | { ok: false; status: 403 }> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
   const recordPages = R.getRecordPages()
   const PageClass = recordPages[subPageSlug]

package/src/plugins/index.ts

@@ -1 +1,8 @@
 export { themeEditor } from './themeEditor.js'
+export type { ThemeEditorOptions } from './themeEditor.js'
+export { prismaThemeStorage } from '../theme/storage.js'
+export type {
+  ThemeStorageAdapter,
+  PanelGlobalDelegate,
+  PrismaThemeStorageOptions,
+} from '../theme/storage.js'