@pilotiq/pilotiq 0.1.0

package/src/schema/sanitize.ts

@@ -0,0 +1,49 @@
+import sanitizeHtmlLib from 'sanitize-html'
+
+export type SanitizeConfig = sanitizeHtmlLib.IOptions
+
+/**
+ * Default-secure allowlist for `Markdown` and `Html` primes — covers prose
+ * content (headings, lists, code, links, images, tables) while blocking
+ * `<script>` / `<iframe>`, inline event handlers, `javascript:` URIs, and
+ * `style` attribute overrides that could break the surrounding admin chrome.
+ *
+ * Pass a custom config to `Markdown.sanitize(...)` / `Html.sanitize(...)`
+ * when an admin-trusted source needs a wider allowlist (e.g. legacy CMS
+ * HTML with embedded media, or a custom block highlighter that emits
+ * `style="color:..."` on inline spans).
+ */
+export const DEFAULT_SANITIZE_CONFIG: SanitizeConfig = {
+  allowedTags: [
+    'p', 'br', 'hr', 'span', 'div',
+    'strong', 'em', 'b', 'i', 'u', 's', 'del', 'ins', 'mark',
+    'sub', 'sup', 'small', 'abbr', 'kbd',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    'ul', 'ol', 'li',
+    'blockquote', 'pre', 'code',
+    'a', 'img',
+    'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td', 'caption',
+  ],
+  allowedAttributes: {
+    a:    ['href', 'title', 'rel', 'target', 'name'],
+    img:  ['src', 'alt', 'title', 'width', 'height'],
+    abbr: ['title'],
+    th:   ['colspan', 'rowspan', 'scope'],
+    td:   ['colspan', 'rowspan'],
+    code: ['class'],
+    pre:  ['class'],
+  },
+  allowedSchemes:        ['http', 'https', 'mailto', 'tel'],
+  allowedSchemesByTag:   { img: ['http', 'https', 'data'] },
+  allowProtocolRelative: false,
+  disallowedTagsMode:    'discard',
+}
+
+/**
+ * Sanitizes an HTML string against `DEFAULT_SANITIZE_CONFIG` (or a
+ * caller-supplied config). Server-side only — never call from a renderer,
+ * since the wire shape ships pre-rendered HTML.
+ */
+export function sanitizeHtml(html: string, config?: SanitizeConfig): string {
+  return sanitizeHtmlLib(html, config ?? DEFAULT_SANITIZE_CONFIG)
+}

package/src/search.test.ts

@@ -0,0 +1,446 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Pilotiq } from './Pilotiq.js'
+import { Resource } from './Resource.js'
+import { Column } from './Column.js'
+import { Table } from './elements/Table.js'
+import type { ModelLike, ModelQuery, ModelWhereOperator } from './orm/modelDefaults.js'
+import { searchAllResources } from './search.js'
+import { searchData } from './pageData.js'
+import { Heading } from './schema/Heading.js'
+import { Text } from './schema/Text.js'
+
+// ─── Fake ModelQuery / ModelLike ────────────────────────────
+
+interface FakeRow { id: string | number; [key: string]: unknown }
+
+function fakeModel(rows: FakeRow[]): ModelLike & {
+  recordedQueries: Array<{ wheres: Array<[string, ModelWhereOperator | unknown, unknown?]>; limit?: number }>
+} {
+  const recordedQueries: Array<{ wheres: Array<[string, ModelWhereOperator | unknown, unknown?]>; limit?: number }> = []
+
+  const M: ModelLike & { recordedQueries: typeof recordedQueries } = {
+    primaryKey: 'id',
+    async find(id) { return rows.find(r => String(r['id']) === String(id)) ?? null },
+    async create(data) { return data },
+    async update(_id, data) { return data },
+    async delete(_id) {},
+    query(): ModelQuery {
+      const wheres: Array<[string, ModelWhereOperator | unknown, unknown?]> = []
+      const matches = (row: FakeRow): boolean => {
+        // OR-of-LIKE only for our tests; column LIKE '%needle%'
+        if (wheres.length === 0) return true
+        return wheres.some(([col, op, val]) => {
+          const haystack = String(row[col as string] ?? '').toLowerCase()
+          if (op === 'LIKE') {
+            const needle = String(val).replace(/^%|%$/g, '').toLowerCase()
+            return haystack.includes(needle)
+          }
+          if (op === undefined) {
+            return String(row[col as string] ?? '') === String(val)
+          }
+          return false
+        })
+      }
+      const q: ModelQuery = {
+        where(col: string, opOrVal: unknown, val?: unknown): ModelQuery {
+          wheres.push([col, val !== undefined ? opOrVal : undefined, val !== undefined ? val : opOrVal])
+          return q
+        },
+        orWhere(col: string, opOrVal: unknown, val?: unknown): ModelQuery {
+          wheres.push([col, val !== undefined ? opOrVal : undefined, val !== undefined ? val : opOrVal])
+          return q
+        },
+        orderBy(_col: string): ModelQuery { return q },
+        async paginate(page: number, perPage = 10) {
+          recordedQueries.push({ wheres: [...wheres], limit: perPage })
+          const matched = rows.filter(matches)
+          const start = (page - 1) * perPage
+          return { data: matched.slice(start, start + perPage), total: matched.length }
+        },
+      }
+      return q
+    },
+    recordedQueries,
+  }
+  return M
+}
+
+// ─── Tests ──────────────────────────────────────────────────
+
+describe('searchAllResources (Plan #12)', () => {
+  it('returns [] for queries shorter than 2 chars', async () => {
+    const M = fakeModel([{ id: '1', title: 'Hello' }])
+    class A extends Resource {
+      static override label = 'Articles'
+      static override slug  = 'articles'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A])
+    assert.deepEqual(await searchAllResources(pilotiq, '',  null), [])
+    assert.deepEqual(await searchAllResources(pilotiq, 'a', null), [])
+  })
+
+  it('skips resources with globalSearch=false', async () => {
+    const M = fakeModel([{ id: '1', title: 'Hello world' }])
+    class A extends Resource {
+      static override label = 'Articles'
+      static override slug  = 'articles'
+      // globalSearch defaults to false
+      static override recordTitleAttribute = 'title'
+      static override model = M
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A])
+    assert.deepEqual(await searchAllResources(pilotiq, 'hello', null), [])
+  })
+
+  it('returns matching rows from opted-in resources', async () => {
+    const M = fakeModel([
+      { id: '1', title: 'Hello world' },
+      { id: '2', title: 'Goodbye' },
+      { id: '3', title: 'Hello again' },
+    ])
+    class A extends Resource {
+      static override label = 'Articles'
+      static override slug  = 'articles'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A])
+    const results = await searchAllResources(pilotiq, 'hello', null)
+    assert.equal(results.length, 2)
+    assert.equal(results[0]!.resource, 'articles')
+    assert.equal(results[0]!.resourceLabel, 'Articles')
+    assert.equal(results[0]!.title, 'Hello world')
+    assert.equal(results[0]!.url, '/admin/articles/1')
+  })
+
+  it('applies subtitle override when set', async () => {
+    const M = fakeModel([{ id: '1', title: 'Post', publishedAt: '2026-04-01' }])
+    class A extends Resource {
+      static override label = 'Articles'
+      static override slug  = 'articles'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+      static override getGlobalSearchResultSubtitle(record: unknown): string | undefined {
+        const r = record as { publishedAt?: string }
+        return r.publishedAt ? `Published ${r.publishedAt}` : undefined
+      }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A])
+    const results = await searchAllResources(pilotiq, 'post', null)
+    assert.equal(results[0]!.subtitle, 'Published 2026-04-01')
+  })
+
+  it('honors getGlobalSearchResultUrl override', async () => {
+    const M = fakeModel([{ id: '99', title: 'Edit me' }])
+    class A extends Resource {
+      static override label = 'Articles'
+      static override slug  = 'articles'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+      static override getGlobalSearchResultUrl(record: unknown, base: string): string {
+        return `${base}/articles/${(record as { id: string }).id}/edit`
+      }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A])
+    const results = await searchAllResources(pilotiq, 'edit', null)
+    assert.equal(results[0]!.url, '/admin/articles/99/edit')
+  })
+
+  it('drops resources where canAccess returns false', async () => {
+    const M1 = fakeModel([{ id: '1', title: 'A1' }])
+    const M2 = fakeModel([{ id: '2', title: 'A2' }])
+    class Visible extends Resource {
+      static override label = 'Visible'
+      static override slug  = 'visible'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M1
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+    }
+    class Hidden extends Resource {
+      static override label = 'Hidden'
+      static override slug  = 'hidden'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M2
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+      static override async canAccess(_user: unknown): Promise<boolean> { return false }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([Visible, Hidden])
+    const results = await searchAllResources(pilotiq, 'A1', null)
+    assert.equal(results.length, 1)
+    assert.equal(results[0]!.resource, 'visible')
+  })
+
+  it('drops resources where canViewAny returns false', async () => {
+    const M = fakeModel([{ id: '1', title: 'Hidden' }])
+    class A extends Resource {
+      static override label = 'Articles'
+      static override slug  = 'articles'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+      static override async canViewAny(_user: unknown): Promise<boolean> { return false }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A])
+    const results = await searchAllResources(pilotiq, 'hidden', null)
+    assert.equal(results.length, 0)
+  })
+
+  it('continues other resources when one throws on getGlobalSearchQuery', async () => {
+    const M1 = fakeModel([{ id: '1', title: 'works' }])
+    class Broken extends Resource {
+      static override label = 'Broken'
+      static override slug  = 'broken'
+      static override globalSearch = true
+      static override getGlobalSearchQuery(_needle: string): ModelQuery | undefined {
+        throw new Error('intentional')
+      }
+    }
+    class OK extends Resource {
+      static override label = 'OK'
+      static override slug  = 'ok'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M1
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([Broken, OK])
+    // Silence the warn during the test.
+    const originalWarn = console.warn
+    console.warn = () => {}
+    try {
+      const results = await searchAllResources(pilotiq, 'works', null)
+      assert.equal(results.length, 1)
+      assert.equal(results[0]!.resource, 'ok')
+    } finally {
+      console.warn = originalWarn
+    }
+  })
+
+  it('returns [] when a resource has no model AND no override', async () => {
+    class A extends Resource {
+      static override label        = 'Modeless'
+      static override slug         = 'modeless'
+      static override globalSearch = true
+      // No model. No getGlobalSearchQuery override. No data source → skip.
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A])
+    const results = await searchAllResources(pilotiq, 'anything', null)
+    assert.equal(results.length, 0)
+  })
+
+  it('caps results per resource via opts.limitPerResource', async () => {
+    const M = fakeModel(Array.from({ length: 20 }, (_, i) => ({ id: String(i), title: `row ${i}` })))
+    class A extends Resource {
+      static override label = 'Many'
+      static override slug  = 'many'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A])
+    const results = await searchAllResources(pilotiq, 'row', null, { limitPerResource: 3 })
+    assert.equal(results.length, 3)
+  })
+
+  it('caps total results across all resources', async () => {
+    const rows = Array.from({ length: 10 }, (_, i) => ({ id: String(i), title: `row ${i}` }))
+    const Ma = fakeModel(rows.map(r => ({ ...r, id: `a-${r.id}` })))
+    const Mb = fakeModel(rows.map(r => ({ ...r, id: `b-${r.id}` })))
+    class A extends Resource {
+      static override label = 'A'
+      static override slug  = 'a'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = Ma
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+    }
+    class B extends Resource {
+      static override label = 'B'
+      static override slug  = 'b'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = Mb
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A, B])
+    const results = await searchAllResources(pilotiq, 'row', null, {
+      limitPerResource: 10,
+      limitTotal:       7,
+    })
+    assert.equal(results.length, 7)
+  })
+
+  it('uses getGlobalSearchQuery override when present', async () => {
+    const M = fakeModel([{ id: '1', title: 'pre-override' }])
+    let queryArg = ''
+    class A extends Resource {
+      static override label = 'Override'
+      static override slug  = 'override'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+      static override getGlobalSearchQuery(needle: string): ModelQuery | undefined {
+        queryArg = needle
+        // Just return the unmodified query so paginate still produces the row.
+        return M.query()
+      }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A])
+    const results = await searchAllResources(pilotiq, 'anything', null)
+    assert.equal(queryArg, 'anything')
+    assert.equal(results.length, 1)
+  })
+
+  it('searchData wraps searchAllResources with resolveUser', async () => {
+    const M = fakeModel([{ id: '1', title: 'searchable' }])
+    let userSeen: unknown = 'untouched'
+    class A extends Resource {
+      static override label = 'Articles'
+      static override slug  = 'articles'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+      static override async canAccess(user: unknown): Promise<boolean> {
+        userSeen = user
+        return true
+      }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A]).user(() => ({ role: 'admin' }))
+    const result = await searchData(pilotiq, 'searchable', { fakeReq: true })
+    assert.equal(result.ok, true)
+    assert.equal(result.results.length, 1)
+    assert.deepEqual(userSeen, { role: 'admin' })
+  })
+
+  it('serializes the resource icon onto each result', async () => {
+    const M = fakeModel([{ id: '1', title: 'AB' }])
+    class A extends Resource {
+      static override label = 'Articles'
+      static override slug  = 'articles'
+      static override icon  = 'newspaper'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A])
+    const results = await searchAllResources(pilotiq, 'AB', null)
+    assert.equal(results[0]!.icon, 'newspaper')
+  })
+
+  it('omits renderHooks key when no global-search hooks registered', async () => {
+    const M = fakeModel([{ id: '1', title: 'searchable' }])
+    class A extends Resource {
+      static override label = 'Articles'
+      static override slug  = 'articles'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A])
+    const result = await searchData(pilotiq, 'searchable')
+    assert.equal('renderHooks' in result, false)
+  })
+
+  it('resolves panels::global-search.results.before/.after when registered', async () => {
+    const M = fakeModel([{ id: '1', title: 'searchable' }])
+    class A extends Resource {
+      static override label = 'Articles'
+      static override slug  = 'articles'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+    }
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A])
+      .renderHook('panels::global-search.results.before', () => [Heading.make('Before')])
+      .renderHook('panels::global-search.results.after',  () => [Text.make('After')])
+    const result = await searchData(pilotiq, 'searchable')
+    assert.equal(result.ok, true)
+    const hooks = result.renderHooks
+    assert.ok(hooks, 'renderHooks should be present')
+    const before = hooks!['panels::global-search.results.before']
+    const after  = hooks!['panels::global-search.results.after']
+    assert.equal(before?.length, 1)
+    assert.equal(after?.length,  1)
+    assert.equal(before![0]!['type'], 'heading')
+    assert.equal(after![0]!['type'],  'text')
+  })
+
+  it('passes resolved user into the global-search hook context', async () => {
+    const M = fakeModel([{ id: '1', title: 'searchable' }])
+    class A extends Resource {
+      static override label = 'Articles'
+      static override slug  = 'articles'
+      static override globalSearch = true
+      static override recordTitleAttribute = 'title'
+      static override model = M
+      static override table(table: Table): Table {
+        return table.columns([Column.make('title').searchable()])
+      }
+    }
+    let userSeen: unknown = 'untouched'
+    const pilotiq = Pilotiq.make('test').path('/admin').resources([A])
+      .user(() => ({ role: 'editor' }))
+      .renderHook('panels::global-search.results.before', (ctx) => {
+        userSeen = ctx.user
+        return [Heading.make('Hi')]
+      })
+    await searchData(pilotiq, 'searchable', { fakeReq: true })
+    assert.deepEqual(userSeen, { role: 'editor' })
+  })
+})

package/src/search.ts

@@ -0,0 +1,178 @@
+/**
+ * Plan #12 — global search.
+ *
+ * Walks every opted-in resource on a panel, runs a per-resource search
+ * query in parallel, and returns a flat list of results suitable for
+ * rendering inside a Cmd+K palette.
+ *
+ * What "opted in" means:
+ *   1. `Resource.globalSearch === true` — the static toggle.
+ *   2. `R.canAccess(user)` AND `R.canViewAny(user)` (Plan #10) both
+ *      resolve true. Failures fail closed (resource silently dropped).
+ *   3. Either `R.getGlobalSearchQuery(needle)` returns a query, OR the
+ *      resource has `static model = …` AND a non-empty
+ *      `globallySearchableAttributes()` array.
+ *
+ * Each surviving resource hits `query.paginate(1, limitPerResource)`
+ * (the same method `modelTableRecords` uses, no new ORM contract).
+ * Results map through `getGlobalSearchResultTitle / Subtitle / Url`
+ * and `serializeIcon(R.icon, R.name)` for transport. The caller
+ * receives a flat array sorted by registration order — the palette
+ * handles visual grouping.
+ */
+import type { Pilotiq } from './Pilotiq.js'
+import type { ResourceClass } from './Resource.js'
+import type { ModelQuery } from './orm/modelDefaults.js'
+import { serializeIcon, type SerializedIcon } from './icons/types.js'
+
+export interface GlobalSearchResult {
+  /** URL slug of the resource, e.g. `'articles'`. Useful for grouping. */
+  resource:      string
+  /** Plural label for headings. */
+  resourceLabel: string
+  /** Pre-serialized icon — string registry key or `{ class }` manifest ref. */
+  icon?:         SerializedIcon
+  /** Stringified primary key. */
+  id:            string
+  /** Big text in the palette row. */
+  title:         string
+  /** Optional second line. */
+  subtitle?:     string
+  /** URL the palette navigates to on Enter. */
+  url:           string
+}
+
+export interface GlobalSearchOptions {
+  /** Cap results PER RESOURCE before merge. Default 5. */
+  limitPerResource?: number
+  /** Cap total results returned. Default 25. */
+  limitTotal?: number
+}
+
+const DEFAULT_PER_RESOURCE = 5
+const DEFAULT_TOTAL        = 25
+const MIN_QUERY_LENGTH     = 2
+
+/**
+ * Search all opted-in resources for `query`. Returns up to
+ * `opts.limitTotal` (default 25) results. Empty/short queries return
+ * `[]` cheaply without touching the DB.
+ */
+export async function searchAllResources(
+  pilotiq: Pilotiq,
+  query:   string,
+  user:    unknown,
+  opts:    GlobalSearchOptions = {},
+): Promise<GlobalSearchResult[]> {
+  const needle = query.trim()
+  if (needle.length < MIN_QUERY_LENGTH) return []
+
+  const limitPerResource = opts.limitPerResource ?? DEFAULT_PER_RESOURCE
+  const limitTotal       = opts.limitTotal       ?? DEFAULT_TOTAL
+
+  const cfg = pilotiq.getConfig()
+  const candidates = cfg.resources.filter(R => R.globalSearch === true)
+  if (candidates.length === 0) return []
+
+  // Authorization gate. `canAccess` AND `canViewAny` must both pass —
+  // we don't surface records the user can't list. Throwing predicates
+  // fail closed (drop the resource).
+  const accessChecks = await Promise.all(
+    candidates.map(async (R) => {
+      try {
+        const ok = (await R.canAccess(user)) && (await R.canViewAny(user))
+        return ok ? R : null
+      } catch {
+        return null
+      }
+    }),
+  )
+  const allowed = accessChecks.filter((R): R is ResourceClass => R !== null)
+  if (allowed.length === 0) return []
+
+  const perResource = await Promise.all(
+    allowed.map(R => searchResource(R, needle, limitPerResource, cfg.path, user)),
+  )
+
+  // Flatten + cap. Registration order preserved.
+  const flat: GlobalSearchResult[] = []
+  for (const chunk of perResource) {
+    for (const r of chunk) {
+      flat.push(r)
+      if (flat.length >= limitTotal) return flat
+    }
+  }
+  return flat
+}
+
+async function searchResource(
+  R:      ResourceClass,
+  needle: string,
+  limit:  number,
+  base:   string,
+  user:   unknown,
+): Promise<GlobalSearchResult[]> {
+  try {
+    const q = buildSearchQuery(R, needle, user)
+    if (!q) return []
+
+    const result = await q.paginate(1, limit)
+    const rows   = (result?.data ?? []) as unknown[]
+    const slug   = R.getSlug()
+    const icon   = serializeIcon(R.icon, R.name)
+
+    return rows.map((record) => {
+      const r        = record as Record<string, unknown>
+      const id       = r['id']
+      const title    = R.getGlobalSearchResultTitle(record)
+      const subtitle = R.getGlobalSearchResultSubtitle(record)
+      const url      = R.getGlobalSearchResultUrl(record, base)
+      const out: GlobalSearchResult = {
+        resource:      slug,
+        resourceLabel: R.label,
+        id:            id !== undefined && id !== null ? String(id) : '',
+        title,
+        url,
+      }
+      if (icon !== undefined)     out.icon     = icon
+      if (subtitle !== undefined) out.subtitle = subtitle
+      return out
+    })
+  } catch (err) {
+    // One resource throwing must not blank the palette — log and drop
+    // its results, the rest still resolve via Promise.all.
+    console.warn(`[pilotiq] global search failed on ${R.name}:`, err)
+    return []
+  }
+}
+
+/**
+ * Build the `ModelQuery` we run for a resource. Picks in this order:
+ *   1. User override `R.getGlobalSearchQuery(needle)`.
+ *   2. Default chain: `R.query({ user })` chained with LIKE on each
+ *      attribute returned from `R.globallySearchableAttributes()`.
+ *
+ * Routes through `R.query(ctx)` (instead of `R.model.query()` directly)
+ * so user-installed scopes — tenant filters, default ordering, etc. —
+ * apply to global-search hits the same way they apply to list pages.
+ *
+ * Returns `undefined` when the resource has no model AND no override —
+ * pilotiq won't load every record into memory just to LIKE-match.
+ */
+function buildSearchQuery(R: ResourceClass, needle: string, user: unknown): ModelQuery | undefined {
+  const override = R.getGlobalSearchQuery(needle)
+  if (override) return override
+  if (!R.model) return undefined
+
+  const attrs = R.globallySearchableAttributes()
+  if (attrs.length === 0) return undefined
+
+  const wildcarded = `%${needle}%`
+  let q = R.query(user != null ? { user } : undefined)
+  attrs.forEach((col, i) => {
+    q = i === 0
+      ? q.where(col,   'LIKE', wildcarded)
+      : q.orWhere(col, 'LIKE', wildcarded)
+  })
+  return q
+}