@pilotiq/pilotiq 0.21.0 → 0.23.0

package/src/plugins/themeEditor.test.ts

@@ -0,0 +1,36 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { Pilotiq } from '../Pilotiq.js'
+import { themeEditor } from './themeEditor.js'
+import type { ThemeStorageAdapter } from '../theme/storage.js'
+
+function makeStubAdapter(): ThemeStorageAdapter {
+  return {
+    async load() { return null },
+    async save() { /* noop */ },
+    async clear() { /* noop */ },
+  }
+}
+
+describe('themeEditor() plugin', () => {
+  it('bare themeEditor() leaves the storage slot undefined (boot resolves it)', () => {
+    const panel = Pilotiq.make('admin').use(themeEditor())
+    assert.equal(panel.getConfig().themeEditor, true)
+    assert.equal(panel.getThemeStorage(), undefined)
+  })
+
+  it('themeEditor({ storage }) stamps the adapter onto the panel', () => {
+    const adapter = makeStubAdapter()
+    const panel = Pilotiq.make('admin').use(themeEditor({ storage: adapter }))
+    assert.equal(panel.getThemeStorage(), adapter)
+  })
+
+  it('themeEditor() can be called on multiple panels without leaking adapters', () => {
+    const a = makeStubAdapter()
+    const b = makeStubAdapter()
+    const panelA = Pilotiq.make('admin').use(themeEditor({ storage: a }))
+    const panelB = Pilotiq.make('billing').use(themeEditor({ storage: b }))
+    assert.equal(panelA.getThemeStorage(), a)
+    assert.equal(panelB.getThemeStorage(), b)
+  })
+})

package/src/plugins/themeEditor.ts

@@ -1,4 +1,24 @@
 import type { PilotiqPlugin } from '../Pilotiq.js'
+import type { ThemeStorageAdapter } from '../theme/storage.js'
+
+export interface ThemeEditorOptions {
+  /**
+   * Override persistence adapter. Defaults to the implicit Prisma
+   * fallback (auto-resolved from `app.make('prisma')` against the
+   * `panelGlobal` row) — that fallback is deprecated; pass an explicit
+   * adapter to opt out and silence the deprecation warning.
+   *
+   * @example
+   * ```ts
+   * import { prismaThemeStorage, themeEditor } from '@pilotiq/pilotiq/plugins'
+   *
+   * .use(themeEditor({
+   *   storage: prismaThemeStorage(prisma, { slug: 'admin__theme' }),
+   * }))
+   * ```
+   */
+  storage?: ThemeStorageAdapter
+}
 
 /**
  * Theme editor plugin — adds an interactive theme customization page
@@ -14,11 +34,12 @@ import type { PilotiqPlugin } from '../Pilotiq.js'
  *   .use(themeEditor())
  * ```
  */
-export function themeEditor(): PilotiqPlugin {
+export function themeEditor(opts: ThemeEditorOptions = {}): PilotiqPlugin {
   return {
     name: 'theme-editor',
     register(panel) {
       panel.enableThemeEditor()
+      if (opts.storage) panel._setThemeStorage(opts.storage)
     },
   }
 }

package/src/react/CollabRoomContext.ts

@@ -22,6 +22,18 @@ export interface CollabRoom {
   ydoc:      unknown
   /** `WebsocketProvider` instance. Opaque to pilotiq core. */
   provider:  unknown
+  /**
+   * Resolves on the provider's first sync. Present when the room is
+   * wired through `@rudderjs/sync/react`'s `CollabRoomManager` (which is
+   * what `@pilotiq-pro/collab@>=0.2`'s `<RecordCollabRoom>` does);
+   * absent for legacy / hand-rolled providers. `useCollabSeed` gates
+   * its seed callback on this Promise — adapters that need a
+   * "fragment-empty?" check after first sync should consume the hook
+   * rather than calling `onProviderSynced` themselves.
+   */
+  synced?:   Promise<void>
+  /** IndexedDB persistence handle, when the room wraps `y-indexeddb`. Opaque. */
+  persistence?: unknown
   /** Presence info for cursors / avatars. Forwarded to the extension factory. */
   user?: {
     name?:  string

package/src/react/FormStateContext.tsx

@@ -72,6 +72,19 @@ export function useFormState(): FormStateApi | null {
  */
 export const FormIdContext = createContext<string>('')
 
+/**
+ * Public accessor for the surrounding form's id, normalized to
+ * `undefined` when no `FormRenderer` is mounted up-tree (the sentinel
+ * empty string maps to `undefined`). Adapter packages — `@pilotiq/tiptap`,
+ * `@pilotiq/codemirror` — consume this via the package's `react` re-export
+ * to scope per-field registries (pending-suggestion appliers, focus
+ * reporters) by form so multi-form pages route correctly to the matching
+ * editor instance.
+ */
+export function useFormId(): string | undefined {
+  return useContext(FormIdContext) || undefined
+}
+
 export interface UseFieldStateResult {
   /** True when the field is inside a controlled form (live fields enabled).
    *  Renderers should fall back to their `defaultValue` path when false.

package/src/react/PendingSuggestionApplierRegistry.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  registerPendingSuggestionApplier,
+  getPendingSuggestionApplier,
+  _clearAppliersForTests,
+} from './PendingSuggestionApplierRegistry.js'
+
+describe('PendingSuggestionApplierRegistry', () => {
+  beforeEach(() => { _clearAppliersForTests() })
+
+  it('returns the scoped applier when both formId and fieldName match', () => {
+    const apply = (): void => {}
+    registerPendingSuggestionApplier('form-1', 'bio', apply)
+    assert.equal(getPendingSuggestionApplier('form-1', 'bio'), apply)
+  })
+
+  it('routes scoped lookups to the matching scoped entry across multi-form pages', () => {
+    // Two editors in two forms register under the same field name but
+    // different formIds — the routing has to disambiguate.
+    const applyA = (): void => {}
+    const applyB = (): void => {}
+    registerPendingSuggestionApplier('form-A', 'summary', applyA)
+    registerPendingSuggestionApplier('form-B', 'summary', applyB)
+    assert.equal(getPendingSuggestionApplier('form-A', 'summary'), applyA)
+    assert.equal(getPendingSuggestionApplier('form-B', 'summary'), applyB)
+  })
+
+  it('falls through to the wildcard slot when no scoped match exists', () => {
+    const wild = (): void => {}
+    registerPendingSuggestionApplier(undefined, 'bio', wild)
+    // formId provided but the registry only has a wildcard entry —
+    // the lookup should still resolve so historic single-form pages keep
+    // working even when consumers thread a formId.
+    assert.equal(getPendingSuggestionApplier('form-1', 'bio'), wild)
+  })
+
+  it('global producer + scoped consumer: undefined-formId lookup finds the scoped entry', () => {
+    // Regression guard for the multi-form fix: after threading `formId`
+    // through the Tiptap adapter hooks, every editor registers scoped
+    // by its surrounding `FormRenderer`'s id. A global producer (no
+    // `formId` stamped on the suggestion) calls
+    // `getPendingSuggestionApplier(undefined, fieldName)` — without the
+    // fallback, the wildcard slot is empty and the suggestion silently
+    // never applies. The fallback returns any matching scoped entry.
+    const scopedApply = (): void => {}
+    registerPendingSuggestionApplier('form-edit', 'bio', scopedApply)
+    assert.equal(getPendingSuggestionApplier(undefined, 'bio'), scopedApply)
+  })
+
+  it('global lookup prefers the explicit wildcard slot over scoped fallback', () => {
+    const wild = (): void => {}
+    const scoped = (): void => {}
+    registerPendingSuggestionApplier('form-edit', 'bio', scoped)
+    registerPendingSuggestionApplier(undefined,    'bio', wild)
+    // Wildcard wins — it was the intent of the original API ("formId
+    // defaults to '*'") and a deliberately-registered wildcard applier
+    // is presumed authoritative.
+    assert.equal(getPendingSuggestionApplier(undefined, 'bio'), wild)
+  })
+
+  it('scoped lookup prefers exact match over wildcard slot', () => {
+    const wild = (): void => {}
+    const scoped = (): void => {}
+    registerPendingSuggestionApplier(undefined,   'bio', wild)
+    registerPendingSuggestionApplier('form-edit', 'bio', scoped)
+    assert.equal(getPendingSuggestionApplier('form-edit', 'bio'), scoped)
+  })
+
+  it('returns undefined when no entry matches the fieldName at all', () => {
+    registerPendingSuggestionApplier('form-A', 'bio', () => {})
+    assert.equal(getPendingSuggestionApplier('form-A', 'subtitle'), undefined)
+    assert.equal(getPendingSuggestionApplier(undefined, 'subtitle'), undefined)
+  })
+
+  it('unregister cleanup drops the entry', () => {
+    const apply = (): void => {}
+    const unregister = registerPendingSuggestionApplier('form-1', 'bio', apply)
+    assert.equal(getPendingSuggestionApplier('form-1', 'bio'), apply)
+    unregister()
+    assert.equal(getPendingSuggestionApplier('form-1', 'bio'), undefined)
+  })
+
+  it('re-registering replaces the previous entry and its unregister no-ops', () => {
+    const first  = (): void => {}
+    const second = (): void => {}
+    const off1 = registerPendingSuggestionApplier('form-1', 'bio', first)
+    registerPendingSuggestionApplier('form-1', 'bio', second) // wins
+    assert.equal(getPendingSuggestionApplier('form-1', 'bio'), second)
+    // First's unregister must NOT delete the second's entry — the
+    // registry tracks identity to defend against unmount-after-remount
+    // racing the cleanup of the just-replaced entry.
+    off1()
+    assert.equal(getPendingSuggestionApplier('form-1', 'bio'), second)
+  })
+})

package/src/react/PendingSuggestionApplierRegistry.ts

@@ -58,6 +58,18 @@ export function registerPendingSuggestionApplier(
  * key first; falls back to the wildcard form ('*') so a producer that
  * pushed a suggestion without `formId` still resolves an applier from
  * a single-form page.
+ *
+ * Global-producer fallback: when the lookup `formId` is `undefined` AND
+ * no wildcard entry is registered, return any single scoped entry
+ * matching `fieldName`. This mirrors the consumer-side filter in
+ * `usePendingSuggestionsForField` which lets undefined formId on either
+ * side pass-through. Editors today register scoped by their surrounding
+ * `FormRenderer`'s id (`useFormId()`), so the wildcard slot is almost
+ * always empty — without this fallback, a producer that pushes without
+ * a formId on a single-form page would silently fail to resolve any
+ * applier. We pick the first scoped match (Map insertion order); when
+ * the page genuinely has multiple forms with the same field name,
+ * producers SHOULD stamp `formId` to disambiguate.
  */
 export function getPendingSuggestionApplier(
   formId:    string | undefined,
@@ -68,7 +80,13 @@ export function getPendingSuggestionApplier(
     if (scoped) return scoped.apply
   }
   const wild = _entries.get(keyFor(undefined, fieldName))
-  return wild?.apply
+  if (wild) return wild.apply
+  if (formId === undefined) {
+    for (const entry of _entries.values()) {
+      if (entry.fieldName === fieldName) return entry.apply
+    }
+  }
+  return undefined
 }
 
 /**

package/src/react/index.ts

@@ -39,6 +39,7 @@ export {
   type CollabRoom,
   type SyncedProviderLike,
 } from './CollabRoomContext.js'
+export { useCollabSeed } from './useCollabSeed.js'
 export {
   registerCollabExtensions,
   getCollabExtensions,
@@ -113,6 +114,7 @@ export {
   FormStateProvider,
   useFieldState,
   useFormState,
+  useFormId,
   useRowBinding,
   type FormStateApi,
   type FormStateProviderProps,

package/src/react/useCollabSeed.ts

@@ -0,0 +1,73 @@
+import { useEffect, useRef, useState } from 'react'
+import type { CollabRoom } from './CollabRoomContext.js'
+
+const SEED_ORIGIN = 'pilotiq-collab-seed'
+
+/**
+ * Run `seedFn` exactly once after the collab room's first sync.
+ *
+ * Mirrors `@rudderjs/sync/react`'s `useCollabSeed` shape — same purpose,
+ * reimplemented here so pilotiq core stays free of any hard runtime dep
+ * on Yjs. The `room` parameter is pilotiq's opaque `CollabRoom`, so the
+ * seed callback receives `doc: unknown` and is responsible for its own
+ * share-type lookup (`doc.getXmlFragment(key)` for Tiptap consumers,
+ * `doc.getText(key)` for CodeMirror, etc.) and its own emptiness check.
+ *
+ * Returns `true` once the seed callback has run (or was skipped because
+ * the room has no `.synced` Promise — i.e. a legacy non-framework
+ * provider), so consumers can gate editor mount / placeholder swap.
+ *
+ * The hook wraps `seedFn` in `doc.transact(..., 'pilotiq-collab-seed')`
+ * so downstream observers can filter the synthetic write. Two peers
+ * mounting against a brand-new record may both see "empty" and both
+ * seed — same race window as the legacy `onProviderSynced` path; the
+ * fix is server-side seed handoff, deferred.
+ */
+export function useCollabSeed(
+  room:    CollabRoom | null,
+  key:     string,
+  seedFn:  (doc: unknown) => void,
+): boolean {
+  const [seeded, setSeeded] = useState(false)
+  const seedFnRef = useRef(seedFn)
+  seedFnRef.current = seedFn
+
+  useEffect(() => {
+    if (!room) {
+      setSeeded(false)
+      return
+    }
+    // Legacy rooms without `.synced` — the room owner is on the hook
+    // for whatever first-sync gating they used to do via
+    // `onProviderSynced`. Mark seeded immediately so the consumer
+    // can mount without a placeholder. No seedFn runs.
+    const syncedPromise = room.synced
+    if (!syncedPromise) {
+      setSeeded(true)
+      return
+    }
+
+    let cancelled = false
+    syncedPromise.then(() => {
+      if (cancelled) return
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const ydoc = room.ydoc as any
+        if (ydoc && typeof ydoc.transact === 'function') {
+          ydoc.transact(() => seedFnRef.current(ydoc), SEED_ORIGIN)
+        } else {
+          seedFnRef.current(ydoc)
+        }
+      } catch { /* ignore — seed is best-effort */ }
+      setSeeded(true)
+    }).catch(() => {
+      // synced rejects when the room is torn down before first sync.
+      // Don't surface as a seed failure — the room is gone.
+      if (!cancelled) setSeeded(false)
+    })
+
+    return () => { cancelled = true }
+  }, [room, key])
+
+  return seeded
+}

package/src/routes/globals.ts

@@ -15,8 +15,7 @@ import {
   normalizeRedirect,
   splitMeta,
   forbidden,
-  checkPolicy,
-  policyAccess,
+  policyGate,
   handleFormState,
   handleFormWizard,
   handleFormCreateOption,
@@ -49,8 +48,7 @@ export function registerGlobalRoutes(
     // POST ${editUrl}/_form/:formId/state
     router.post(`${editUrl}/_form/:formId/state`, async (req, res) => {
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, true)
-      if (!await checkPolicy(() => G.canEdit(user, undefined))) return forbidden(res, true)
+      if (!await policyGate(G, user, () => G.canEdit(user, undefined))) return forbidden(res, true)
       const formId = req.params['formId']!
       return handleFormState(req, res, pilotiq, { kind: 'global-edit', slug }, formId)
     })
@@ -58,8 +56,7 @@ export function registerGlobalRoutes(
     // Plan #8 wizard step-validate endpoint for the global's edit form.
     router.post(`${editUrl}/_form/:formId/wizard`, async (req, res) => {
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, true)
-      if (!await checkPolicy(() => G.canEdit(user, undefined))) return forbidden(res, true)
+      if (!await policyGate(G, user, () => G.canEdit(user, undefined))) return forbidden(res, true)
       const formId = req.params['formId']!
       return handleFormWizard(req, res, pilotiq, { kind: 'global-edit', slug }, formId)
     })
@@ -67,8 +64,7 @@ export function registerGlobalRoutes(
     // Async-mention endpoint for the global's edit form.
     router.post(`${editUrl}/_form/:formId/mentions`, async (req, res) => {
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, true)
-      if (!await checkPolicy(() => G.canEdit(user, undefined))) return forbidden(res, true)
+      if (!await policyGate(G, user, () => G.canEdit(user, undefined))) return forbidden(res, true)
       const formId = req.params['formId']!
       return handleFormMentions(req, res, pilotiq, { kind: 'global-edit', slug }, formId)
     })
@@ -76,8 +72,7 @@ export function registerGlobalRoutes(
     // SelectField inline-create modal endpoint for the global's edit form.
     router.post(`${editUrl}/_form/:formId/create-option/:fieldName`, async (req, res) => {
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, true)
-      if (!await checkPolicy(() => G.canEdit(user, undefined))) return forbidden(res, true)
+      if (!await policyGate(G, user, () => G.canEdit(user, undefined))) return forbidden(res, true)
       const formId    = req.params['formId']!
       const fieldName = req.params['fieldName']!
       return handleFormCreateOption(req, res, pilotiq, { kind: 'global-edit', slug }, formId, fieldName)
@@ -85,11 +80,10 @@ export function registerGlobalRoutes(
 
     router.get(editUrl, async (req, res) => {
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, wantsJson(req))
       // Globals carry their record on the singleton form's `loadRecord`;
       // we don't pre-load here — pass a stub so canEdit's signature is
       // honored, and let user code decide whether to consult it.
-      if (!await checkPolicy(() => G.canEdit(user, undefined))) return forbidden(res, wantsJson(req))
+      if (!await policyGate(G, user, () => G.canEdit(user, undefined))) return forbidden(res, wantsJson(req))
       const data = await globalEditData(pilotiq, slug, undefined, req)
       return view('pilotiq.slug', data ?? {})
     })
@@ -100,8 +94,7 @@ export function registerGlobalRoutes(
       const json = wantsJson(req)
 
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, json)
-      if (!await checkPolicy(() => G.canEdit(user, undefined))) return forbidden(res, json)
+      if (!await policyGate(G, user, () => G.canEdit(user, undefined))) return forbidden(res, json)
 
       const ctx: SchemaContext = { mode: 'edit', basePath: base, ...(user !== null ? { user: user as NonNullable<SchemaContext['user']> } : {}) }
       const elements = await callPageSchema(PageClass, ctx)
@@ -147,8 +140,7 @@ export function registerGlobalRoutes(
   if (pages.view) {
     router.get(`${editUrl}/view`, async (req, res) => {
       const user = await pilotiq.resolveUser(req)
-      if (!await policyAccess(G, user)) return forbidden(res, wantsJson(req))
-      if (!await checkPolicy(() => G.canView(user, undefined))) return forbidden(res, wantsJson(req))
+      if (!await policyGate(G, user, () => G.canView(user, undefined))) return forbidden(res, wantsJson(req))
       const data = await globalViewData(pilotiq, slug, req)
       return view('pilotiq.resource-view', data ?? {})
     })