@pilotiq/pilotiq 0.21.0 → 0.22.0

package/dist/theme/storage.js

@@ -0,0 +1,52 @@
+/**
+ * Default storage adapter — writes JSON to the `panelGlobal` row keyed
+ * by `opts.slug`. The Prisma delegate is dependency-injected so consumers
+ * pick how to resolve it (e.g. `app.make('prisma')`, a direct import, a
+ * test stub).
+ *
+ * @example
+ * ```ts
+ * import { Pilotiq } from '@pilotiq/pilotiq'
+ * import { themeEditor, prismaThemeStorage } from '@pilotiq/pilotiq/plugins'
+ *
+ * const adminPanel = Pilotiq.make('Admin')
+ *   .use(themeEditor({
+ *     storage: prismaThemeStorage(prisma, { slug: 'admin__theme' }),
+ *   }))
+ * ```
+ */
+export function prismaThemeStorage(prisma, opts) {
+    const { slug } = opts;
+    return {
+        async load() {
+            const row = await prisma.panelGlobal.findUnique({ where: { slug } });
+            if (!row?.data)
+                return null;
+            const raw = typeof row.data === 'string' ? JSON.parse(row.data) : row.data;
+            return raw;
+        },
+        async save(overrides) {
+            const data = JSON.stringify(overrides);
+            await prisma.panelGlobal.upsert({
+                where: { slug },
+                update: { data },
+                create: { slug, data },
+            });
+        },
+        async clear() {
+            try {
+                await prisma.panelGlobal.delete({ where: { slug } });
+            }
+            catch (e) {
+                if (!isRecordNotFound(e))
+                    throw e;
+            }
+        },
+    };
+}
+function isRecordNotFound(e) {
+    return typeof e === 'object'
+        && e !== null
+        && e.code === 'P2025';
+}
+//# sourceMappingURL=storage.js.map

package/dist/theme/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/theme/storage.ts"],"names":[],"mappings":"AAsDA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAA2B,EAC3B,IAAiC;IAEjC,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAA;IACrB,OAAO;QACL,KAAK,CAAC,IAAI;YACR,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;YACpE,IAAI,CAAC,GAAG,EAAE,IAAI;gBAAE,OAAO,IAAI,CAAA;YAC3B,MAAM,GAAG,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAA;YAC1E,OAAO,GAA2B,CAAA;QACpC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,SAAS;YAClB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;YACtC,MAAM,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC;gBAC9B,KAAK,EAAG,EAAE,IAAI,EAAE;gBAChB,MAAM,EAAE,EAAE,IAAI,EAAE;gBAChB,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;aACvB,CAAC,CAAA;QACJ,CAAC;QACD,KAAK,CAAC,KAAK;YACT,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;YACtD,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;oBAAE,MAAM,CAAC,CAAA;YACnC,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,CAAU;IAClC,OAAO,OAAO,CAAC,KAAK,QAAQ;WACvB,CAAC,KAAK,IAAI;WACT,CAAuB,CAAC,IAAI,KAAK,OAAO,CAAA;AAChD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotiq/pilotiq",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "View-based admin panel for RudderJS",
   "license": "MIT",
   "repository": {

package/src/Pilotiq.perf.test.ts

@@ -0,0 +1,252 @@
+/**
+ * Phase 5 perf sweep — covers the four hot-path changes that landed
+ * 2026-05-22:
+ *
+ *  - 5b Per-user navigation-badge TTL cache (`Pilotiq.navigationBadgeTtl`)
+ *  - 5c Map-based slug lookup (`Pilotiq.findResource/findGlobal/findPage`)
+ *  - 5a Chunked import (`importFactory.runImport` honors `concurrency`)
+ *
+ *  5d (`policyGate`) is exercised indirectly by the existing routes /
+ *  authorization tests — its contract is identical to the prior
+ *  serial pair, just parallelized; no behavior change to assert here.
+ */
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Pilotiq } from './Pilotiq.js'
+import { Resource } from './Resource.js'
+import { Global } from './Global.js'
+import { Page } from './Page.js'
+import { runImport } from './actions/importFactory.js'
+
+// ─── Fixtures ─────────────────────────────────────────────────
+
+class Articles extends Resource {
+  static override slug = 'articles'
+  static override label = 'Articles'
+}
+class Comments extends Resource {
+  static override slug = 'comments'
+  static override label = 'Comments'
+}
+class Settings extends Global {
+  static override slug = 'settings'
+  static override label = 'Settings'
+}
+class Branding extends Global {
+  static override slug = 'branding'
+  static override label = 'Branding'
+}
+class Reports extends Page {
+  static override slug = 'reports'
+  static override label = 'Reports'
+}
+class Health extends Page {
+  static override slug = 'health'
+  static override label = 'Health'
+}
+
+// ─── 5c — Map-based slug lookup ───────────────────────────────
+
+describe('Pilotiq.find{Resource,Global,Page}() — Plan 5c', () => {
+  it('returns the matching class by slug', () => {
+    const p = Pilotiq.make('admin')
+      .resources([Articles, Comments])
+      .globals([Settings, Branding])
+      .pages([Reports, Health])
+    assert.equal(p.findResource('articles'), Articles)
+    assert.equal(p.findResource('comments'), Comments)
+    assert.equal(p.findGlobal('settings'),   Settings)
+    assert.equal(p.findGlobal('branding'),   Branding)
+    assert.equal(p.findPage('reports'),      Reports)
+    assert.equal(p.findPage('health'),       Health)
+  })
+
+  it('returns undefined for unknown slugs', () => {
+    const p = Pilotiq.make('admin').resources([Articles])
+    assert.equal(p.findResource('nope'), undefined)
+    assert.equal(p.findGlobal('nope'),   undefined)
+    assert.equal(p.findPage('nope'),     undefined)
+  })
+
+  it('invalidates the cache when .resources() is reassigned', () => {
+    const p = Pilotiq.make('admin').resources([Articles])
+    assert.equal(p.findResource('articles'), Articles)
+    assert.equal(p.findResource('comments'), undefined)
+    p.resources([Articles, Comments])
+    assert.equal(p.findResource('comments'), Comments)
+  })
+
+  it('invalidates the page cache when .pages() is reassigned', () => {
+    const p = Pilotiq.make('admin').pages([Reports])
+    assert.equal(p.findPage('reports'), Reports)
+    assert.equal(p.findPage('health'),  undefined)
+    p.pages([Reports, Health])
+    assert.equal(p.findPage('health'), Health)
+  })
+
+  it('invalidates the page cache when .dashboard()/.profile() auto-append', () => {
+    class Dash extends Page {
+      static override slug = 'dash'
+      static override label = 'Dashboard'
+    }
+    const p = Pilotiq.make('admin')
+    assert.equal(p.findPage('dash'), undefined)
+    p.dashboard(Dash)
+    assert.equal(p.findPage('dash'), Dash)
+  })
+})
+
+// ─── 5b — Navigation badge TTL cache ──────────────────────────
+
+describe('Pilotiq.navigationBadgeTtl() + resolveNavigationBadge() — Plan 5b', () => {
+  it('default TTL is 30s', () => {
+    const p = Pilotiq.make('admin')
+    assert.equal(p.getNavigationBadgeTtl(), 30_000)
+  })
+
+  it('navigationBadgeTtl(ms) overrides; clamps negatives to 0', () => {
+    const p = Pilotiq.make('admin').navigationBadgeTtl(5_000)
+    assert.equal(p.getNavigationBadgeTtl(), 5_000)
+    p.navigationBadgeTtl(-1)
+    assert.equal(p.getNavigationBadgeTtl(), 0)
+  })
+
+  it('navigationBadgeTtl(null) restores the default', () => {
+    const p = Pilotiq.make('admin').navigationBadgeTtl(1_000)
+    p.navigationBadgeTtl(null)
+    assert.equal(p.getNavigationBadgeTtl(), 30_000)
+  })
+
+  it('resolveNavigationBadge caches within TTL, busts on user change', async () => {
+    const p = Pilotiq.make('admin')
+    let calls = 0
+    const resolver = async () => { calls++; return String(calls) }
+
+    // First call: miss → resolver fires → returns '1'.
+    assert.equal(await p.resolveNavigationBadge('Articles', { id: 1 }, resolver), '1')
+    assert.equal(calls, 1)
+    // Same user + owner: hit → no new call → still '1'.
+    assert.equal(await p.resolveNavigationBadge('Articles', { id: 1 }, resolver), '1')
+    assert.equal(calls, 1)
+    // Different user: miss → resolver fires again.
+    assert.equal(await p.resolveNavigationBadge('Articles', { id: 2 }, resolver), '2')
+    assert.equal(calls, 2)
+    // Different owner, same user: separate cache slot.
+    assert.equal(await p.resolveNavigationBadge('Comments', { id: 1 }, resolver), '3')
+    assert.equal(calls, 3)
+  })
+
+  it('TTL of 0 disables caching entirely', async () => {
+    const p = Pilotiq.make('admin').navigationBadgeTtl(0)
+    let calls = 0
+    const resolver = async () => { calls++; return 'x' }
+    await p.resolveNavigationBadge('Articles', { id: 1 }, resolver)
+    await p.resolveNavigationBadge('Articles', { id: 1 }, resolver)
+    assert.equal(calls, 2)
+  })
+
+  it('caches undefined results (no need to keep re-resolving "no badge")', async () => {
+    const p = Pilotiq.make('admin')
+    let calls = 0
+    const resolver = async () => { calls++; return undefined }
+    assert.equal(await p.resolveNavigationBadge('Articles', null, resolver), undefined)
+    assert.equal(await p.resolveNavigationBadge('Articles', null, resolver), undefined)
+    assert.equal(calls, 1)
+  })
+
+  it('navigationBadgeTtl(ms) clears the cache', async () => {
+    const p = Pilotiq.make('admin')
+    let calls = 0
+    const resolver = async () => { calls++; return 'x' }
+    await p.resolveNavigationBadge('A', null, resolver)
+    assert.equal(calls, 1)
+    p.navigationBadgeTtl(60_000)
+    await p.resolveNavigationBadge('A', null, resolver)
+    assert.equal(calls, 2)
+  })
+
+  it('anonymous users share one cache slot', async () => {
+    const p = Pilotiq.make('admin')
+    let calls = 0
+    const resolver = async () => { calls++; return 'x' }
+    await p.resolveNavigationBadge('A', null,      resolver)
+    await p.resolveNavigationBadge('A', undefined, resolver)
+    assert.equal(calls, 1)
+  })
+
+  it('falls back to JSON.stringify when user has no .id', async () => {
+    const p = Pilotiq.make('admin')
+    let calls = 0
+    const resolver = async () => { calls++; return 'x' }
+    await p.resolveNavigationBadge('A', { role: 'editor' }, resolver)
+    await p.resolveNavigationBadge('A', { role: 'editor' }, resolver)
+    assert.equal(calls, 1) // same JSON shape → cache hit
+    await p.resolveNavigationBadge('A', { role: 'admin'  }, resolver)
+    assert.equal(calls, 2) // different JSON → miss
+  })
+})
+
+// ─── 5a — Chunked importFactory.runImport ─────────────────────
+
+describe('importFactory.runImport — Plan 5a chunking', () => {
+  it('runs rows in chunks of `concurrency` and aggregates counts', async () => {
+    const created: string[] = []
+    let maxInFlight = 0
+    let inFlight = 0
+    const M = {
+      async create(row: { id: string }) {
+        inFlight++; if (inFlight > maxInFlight) maxInFlight = inFlight
+        await new Promise(r => setTimeout(r, 5))
+        inFlight--
+        created.push(row.id)
+      },
+      // unused for create-mode tests but the type wants them present
+      query() { return { where() { return { paginate: async () => ({ data: [] }) } } } },
+      async update() {},
+    }
+    const rows = Array.from({ length: 25 }, (_, i) => ({ id: `r${i}` }))
+    const summary = await runImport(rows, M, 'create', { concurrency: 5 }, { request: undefined })
+    assert.equal(summary.created, 25)
+    assert.equal(summary.errors.length, 0)
+    // With concurrency=5 we should see at least 4 in-flight at peak.
+    assert.ok(maxInFlight >= 4, `expected >=4 concurrent, saw ${maxInFlight}`)
+    // Never exceed the cap.
+    assert.ok(maxInFlight <= 5, `expected <=5 concurrent, saw ${maxInFlight}`)
+  })
+
+  it('preserves original-row indices in error messages despite chunking', async () => {
+    const M = {
+      async create(row: { id: string }) {
+        if (row.id === 'r2') throw new Error('boom')
+      },
+      query() { return { where() { return { paginate: async () => ({ data: [] }) } } } },
+      async update() {},
+    }
+    const rows = [{ id: 'r0' }, { id: 'r1' }, { id: 'r2' }, { id: 'r3' }]
+    const summary = await runImport(rows, M, 'create', { concurrency: 4 }, { request: undefined })
+    assert.equal(summary.created, 3)
+    assert.equal(summary.skipped, 1)
+    assert.equal(summary.errors.length, 1)
+    assert.equal(summary.errors[0]?.row, 3) // 1-based, original index 2 → row 3
+    assert.match(summary.errors[0]?.message ?? '', /boom/)
+  })
+
+  it('defaults to concurrency 10 when unset', async () => {
+    let maxInFlight = 0
+    let inFlight = 0
+    const M = {
+      async create() {
+        inFlight++; if (inFlight > maxInFlight) maxInFlight = inFlight
+        await new Promise(r => setTimeout(r, 3))
+        inFlight--
+      },
+      query() { return { where() { return { paginate: async () => ({ data: [] }) } } } },
+      async update() {},
+    }
+    const rows = Array.from({ length: 30 }, () => ({}))
+    await runImport(rows, M, 'create', {}, { request: undefined })
+    assert.ok(maxInFlight <= 10, `expected <=10 concurrent, saw ${maxInFlight}`)
+    assert.ok(maxInFlight >= 5,  `expected >=5 concurrent under default, saw ${maxInFlight}`)
+  })
+})

package/src/Pilotiq.test.ts

@@ -62,6 +62,10 @@ function makeStubRouter(): Router & { _calls: Array<{ method: string; path: stri
     put:    (path: string) => noop(path),
     delete: (path: string) => noop(path),
     patch:  (path: string) => noop(path),
+    // `router.group(opts, fn)` runs `fn()` synchronously inside its
+    // scope. Stub mirrors that — `Pilotiq.guard()` middleware doesn't
+    // touch the stub, only `fn()` matters.
+    group:  (_opts: unknown, fn: () => void) => { fn() },
     _calls: calls,
   }
   return stub

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 ──────────────────────────────────────────────
 
 /**