@lowdefy/server-dev 6.1.0 → 7.1.0

package/lib/docs/screenshotPage.test.mjs

@@ -25,6 +25,18 @@ import { jest } from '@jest/globals';
 // browser flow is untouched everywhere else.
 jest.unstable_mockModule('playwright-core', () => ({
   chromium: { launch: jest.fn().mockRejectedValue(new Error("Executable doesn't exist")) },
+  selectors: { register: jest.fn(async () => {}) },
+}));
+// A missing shell would otherwise start a real download.
+jest.unstable_mockModule('./installHeadlessShell.js', () => ({ default: () => null }));
+// A data set caller loads a data set into the dev server's memory store; both
+// are mocked so the test checks who the page opens as and on which database.
+const mockReadDataSet = jest.fn();
+const mockOpenDataSession = jest.fn();
+jest.unstable_mockModule('./dataSets/readDataSet.js', () => ({ default: mockReadDataSet }));
+jest.unstable_mockModule('./dataSets/getDataStore.js', () => ({ default: async () => ({}) }));
+jest.unstable_mockModule('./dataSets/openDataSession.js', () => ({
+  default: mockOpenDataSession,
 }));
 
 // lib/build/config.js reads build/config.json from process.cwd() at import
@@ -34,6 +46,10 @@ const originalCwd = process.cwd();
 const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-screenshot-test-'));
 fs.mkdirSync(path.join(fixtureDir, 'build'), { recursive: true });
 fs.writeFileSync(path.join(fixtureDir, 'build', 'config.json'), JSON.stringify({ basePath: '' }));
+fs.writeFileSync(
+  path.join(fixtureDir, 'build', 'routes.json'),
+  JSON.stringify([{ pageId: 'ticket', path: 'tickets/{space}/{ticket_id}' }])
+);
 process.chdir(fixtureDir);
 
 const { default: screenshotPage } = await import('./screenshotPage.js');
@@ -55,5 +71,251 @@ test('screenshotPage returns an error when pageId is missing', async () => {
 
 test('screenshotPage returns an actionable error when no browser is available', async () => {
   const result = await screenshotPage({ origin: 'http://localhost:3001', pageId: 'home' });
-  expect(result.error).toMatch(/No Chromium available. Run: npx playwright install chromium/);
+  expect(result.error).toMatch(
+    /No Chromium available. Run: npx playwright install chromium-headless-shell/
+  );
+});
+
+test('screenshotPage returns an error for an invalid viewport before launching a browser', async () => {
+  const { chromium } = await import('playwright-core');
+  chromium.launch.mockClear();
+  const width = await screenshotPage({ origin: 'http://localhost:3001', pageId: 'home', width: 0 });
+  expect(width.error).toEqual(
+    'Viewport width must be a positive integer of at most 4096 (CSS pixels). Received 0.'
+  );
+  const scheme = await screenshotPage({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    colorScheme: 'sepia',
+  });
+  expect(scheme.error).toEqual('Color scheme must be "light" or "dark". Received "sepia".');
+  expect(chromium.launch).not.toHaveBeenCalled();
+});
+
+test('screenshotPage rejects a bad urlQuery or malformed steps before launching a browser', async () => {
+  const { chromium } = await import('playwright-core');
+  chromium.launch.mockClear();
+  const query = await screenshotPage({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    urlQuery: 'framework=popia',
+  });
+  expect(query.error).toMatch(/requires "urlQuery" to be an object/);
+  const steps = await screenshotPage({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    steps: [{ hover: 'x' }],
+  });
+  expect(steps.error).toMatch(/Unknown journey step "hover"/);
+  expect(chromium.launch).not.toHaveBeenCalled();
+});
+
+test('screenshotPage opens the page at the urlQuery and captures after the steps ran', async () => {
+  const { chromium } = await import('playwright-core');
+  const calls = [];
+  const page = {
+    goto: jest.fn(async (url) => calls.push(`goto ${url}`)),
+    waitForFunction: jest.fn(async () => {}),
+    waitForTimeout: jest.fn(async () => {}),
+    screenshot: jest.fn(async () => {
+      calls.push('screenshot');
+      return Buffer.from('png');
+    }),
+  };
+  const context = {
+    addCookies: jest.fn(async () => {}),
+    newPage: jest.fn(async () => page),
+    close: jest.fn(async () => {}),
+    on: jest.fn(),
+  };
+  // getBrowser caches the browser while it reports connected; disconnecting
+  // it after the test makes the next test's launch take effect.
+  let connected = true;
+  chromium.launch.mockResolvedValue({
+    isConnected: () => connected,
+    newContext: async () => context,
+  });
+  try {
+    const result = await screenshotPage({
+      origin: 'http://localhost:3001',
+      pageId: 'gates',
+      urlQuery: { framework: 'popia', filter: { status: 'open' } },
+    });
+    expect(result.mimeType).toEqual('image/png');
+    expect(page.goto).toHaveBeenCalledTimes(1);
+    const url = new URL(page.goto.mock.calls[0][0]);
+    expect(url.pathname).toEqual('/gates');
+    expect(url.search).not.toEqual('');
+    expect(decodeURIComponent(url.search)).toContain('popia');
+    expect(context.close).toHaveBeenCalled();
+  } finally {
+    connected = false;
+    chromium.launch.mockRejectedValue(new Error("Executable doesn't exist"));
+  }
+});
+
+test('screenshotPage refuses steps that read email when the dev server captures no mail', async () => {
+  const { chromium } = await import('playwright-core');
+  chromium.launch.mockClear();
+  const result = await screenshotPage({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    steps: [{ email: { to: 'a@example.com' } }],
+  });
+  expect(result.error).toMatch(/captures no mail/);
+  expect(chromium.launch).not.toHaveBeenCalled();
+});
+
+test('screenshotPage keeps the colour scheme and returns screenshot step captures when steps run', async () => {
+  const { chromium } = await import('playwright-core');
+  let captures = 0;
+  const page = {
+    goto: jest.fn(async () => {}),
+    waitForFunction: jest.fn(async () => {}),
+    waitForTimeout: jest.fn(async () => {}),
+    screenshot: jest.fn(async () => {
+      captures += 1;
+      return Buffer.from(`png-${captures}`);
+    }),
+  };
+  const context = {
+    addCookies: jest.fn(async () => {}),
+    // A journey's network counter listens for the context's requests.
+    on: jest.fn(),
+    // Its pages report what they ran through the journey observer binding.
+    exposeBinding: jest.fn(async () => {}),
+    newPage: jest.fn(async () => page),
+    close: jest.fn(async () => {}),
+  };
+  const newContext = jest.fn(async () => context);
+  let connected = true;
+  chromium.launch.mockResolvedValue({ isConnected: () => connected, newContext });
+  try {
+    const result = await screenshotPage({
+      origin: 'http://localhost:3001',
+      pageId: 'home',
+      colorScheme: 'dark',
+      steps: [{ screenshot: 'before' }],
+    });
+    expect(newContext).toHaveBeenCalledWith(expect.objectContaining({ colorScheme: 'dark' }));
+    expect(result.screenshots).toEqual([
+      { name: 'before', data: Buffer.from('png-1').toString('base64'), mimeType: 'image/png' },
+    ]);
+    expect(result.data).toEqual(Buffer.from('png-2').toString('base64'));
+    expect(context.close).toHaveBeenCalled();
+  } finally {
+    connected = false;
+    chromium.launch.mockRejectedValue(new Error("Executable doesn't exist"));
+  }
+});
+
+test('screenshotPage returns the error naming a missing placeholder before opening a browser', async () => {
+  const result = await screenshotPage({
+    origin: 'http://localhost:3001',
+    pageId: 'ticket',
+    pathParams: { space: 's' },
+  });
+  expect(result.invalidInput).toBe(true);
+  expect(result.error).toMatch(/missing a value for path placeholder "ticket_id"/);
+});
+
+test('screenshotPage refuses a data set user name without data before launching a browser', async () => {
+  const { chromium } = await import('playwright-core');
+  chromium.launch.mockClear();
+  const result = await screenshotPage({
+    origin: 'http://localhost:3001',
+    pageId: 'home',
+    user: 'member',
+  });
+  expect(result).toEqual({
+    error:
+      'The call\'s user "member" names a data set user, but the call has no "data". Add data: <data set name>, or give user as an object.',
+    invalidInput: true,
+  });
+  expect(chromium.launch).not.toHaveBeenCalled();
+});
+
+test("screenshotPage renders as a data set user, on the data set's own database", async () => {
+  const { chromium } = await import('playwright-core');
+  const member = { id: 'u_member', roles: ['member'] };
+  mockReadDataSet.mockResolvedValue({ name: 'crm', users: { member } });
+  const close = jest.fn(async () => {});
+  mockOpenDataSession.mockResolvedValue({ cookie: 'session1', session: { id: 'session1' }, close });
+  const page = {
+    goto: jest.fn(async () => {}),
+    waitForFunction: jest.fn(async () => {}),
+    waitForTimeout: jest.fn(async () => {}),
+    screenshot: jest.fn(async () => Buffer.from('png')),
+  };
+  const cookies = [];
+  const context = {
+    addCookies: jest.fn(async (added) => cookies.push(...added)),
+    route: jest.fn(async () => {}),
+    newPage: jest.fn(async () => page),
+    close: jest.fn(async () => {}),
+    on: jest.fn(),
+  };
+  let connected = true;
+  chromium.launch.mockResolvedValue({
+    isConnected: () => connected,
+    newContext: async () => context,
+  });
+  try {
+    const result = await screenshotPage({
+      origin: 'http://localhost:3001',
+      pageId: 'home',
+      user: 'member',
+      data: 'crm',
+    });
+    expect(result.mimeType).toEqual('image/png');
+    expect(mockReadDataSet).toHaveBeenCalledWith(expect.objectContaining({ name: 'crm' }));
+    expect(mockOpenDataSession).toHaveBeenCalledWith({
+      dataSet: { name: 'crm', users: { member } },
+    });
+    const headless = cookies.find((cookie) => cookie.name === 'lowdefy_headless_user');
+    const caller = JSON.parse(Buffer.from(headless.value, 'base64').toString());
+    expect(caller.explicit).toBe(true);
+    expect(caller.user).toMatchObject({ id: 'u_member', roles: ['member'] });
+    expect(cookies.map((cookie) => cookie.name)).toContain('lowdefy_journey_data');
+    expect(close).toHaveBeenCalledTimes(1);
+  } finally {
+    connected = false;
+    chromium.launch.mockRejectedValue(new Error("Executable doesn't exist"));
+  }
+});
+
+test('screenshotPage opens the page signed out for user "none"', async () => {
+  const { chromium } = await import('playwright-core');
+  mockOpenDataSession.mockClear();
+  const page = {
+    goto: jest.fn(async () => {}),
+    waitForFunction: jest.fn(async () => {}),
+    waitForTimeout: jest.fn(async () => {}),
+    screenshot: jest.fn(async () => Buffer.from('png')),
+  };
+  const cookies = [];
+  const context = {
+    addCookies: jest.fn(async (added) => cookies.push(...added)),
+    newPage: jest.fn(async () => page),
+    close: jest.fn(async () => {}),
+    on: jest.fn(),
+  };
+  let connected = true;
+  chromium.launch.mockResolvedValue({
+    isConnected: () => connected,
+    newContext: async () => context,
+  });
+  try {
+    const result = await screenshotPage({
+      origin: 'http://localhost:3001',
+      pageId: 'home',
+      user: 'none',
+    });
+    expect(result.mimeType).toEqual('image/png');
+    expect(cookies.map((cookie) => cookie.name)).not.toContain('lowdefy_headless_user');
+    expect(mockOpenDataSession).not.toHaveBeenCalled();
+  } finally {
+    connected = false;
+    chromium.launch.mockRejectedValue(new Error("Executable doesn't exist"));
+  }
 });

package/lib/docs/screenshotPageClip.test.mjs

@@ -37,6 +37,10 @@ const mockOpenPage = jest.fn(async () => ({
 }));
 const mockGetBrowser = jest.fn(async () => ({}));
 
+// The route table is a build artifact these tests have none of: every page is served at its id.
+jest.unstable_mockModule('./resolvePageInstance.js', () => ({
+  default: ({ pageId }) => ({ path: pageId, instanceKey: `page:${pageId}` }),
+}));
 jest.unstable_mockModule('./getBrowser.js', () => ({
   getBrowser: mockGetBrowser,
   openPage: mockOpenPage,

package/lib/docs/searchDocs.js

@@ -14,54 +14,106 @@
   limitations under the License.
 */
 
-import fs from 'node:fs';
-import path from 'node:path';
 import { type } from '@lowdefy/helpers';
 
-import getDocsManifest from './getDocsManifest.js';
+import docSources from './docSources.js';
+import getDocsIndex from './getDocsIndex.js';
+import readDocEntry from './readDocEntry.js';
+import splitSearchTerms from './splitSearchTerms.js';
 
 const MAX_RESULTS = 20;
 const SNIPPET_RADIUS = 120;
+const TITLE_WEIGHT = 3;
+const TYPE_NAME_WEIGHT = 2;
+const BODY_WEIGHT = 1;
 
-let contentCache = null;
+// Each term counts once, in the best field it appears in.
+function scoreEntry({ entry, content, terms }) {
+  const title = entry.title.toLowerCase();
+  const slug = entry.slug.toLowerCase();
+  const typeName = (entry.typeName ?? '').toLowerCase();
+  const body = content.toLowerCase();
+  let score = 0;
+  let titleMatched = false;
+  let bodyMatch = null;
+  for (const term of terms) {
+    if (title.includes(term) || slug.includes(term)) {
+      score += TITLE_WEIGHT;
+      titleMatched = true;
+      continue;
+    }
+    if (typeName.includes(term)) {
+      score += TYPE_NAME_WEIGHT;
+      continue;
+    }
+    const index = body.indexOf(term);
+    if (index !== -1) {
+      score += BODY_WEIGHT;
+      bodyMatch = bodyMatch ?? { index, term };
+    }
+  }
+  return { score, titleMatched, bodyMatch };
+}
 
-function getContents({ manifest }) {
-  if (contentCache !== null) {
-    return contentCache;
+function makeSnippet({ content, titleMatched, bodyMatch }) {
+  if (titleMatched || type.isNone(bodyMatch)) {
+    return content.slice(0, SNIPPET_RADIUS * 2);
   }
-  contentCache = manifest.docs.map((doc) => ({
-    doc,
-    content: fs.readFileSync(path.join(manifest.contentDir, doc.path), 'utf8'),
-  }));
-  return contentCache;
+  const start = Math.max(0, bodyMatch.index - SNIPPET_RADIUS);
+  return content.slice(start, bodyMatch.index + bodyMatch.term.length + SNIPPET_RADIUS);
 }
 
-function searchDocs({ query }) {
+function makeHit({ entry, snippet }) {
+  const hit = { slug: entry.slug, title: entry.title, section: entry.section };
+  if (!type.isNone(entry.kind)) {
+    hit.kind = entry.kind;
+  }
+  if (!type.isNone(entry.typeName)) {
+    hit.typeName = entry.typeName;
+  }
+  hit.source = entry.source;
+  hit.package = entry.package;
+  hit.version = entry.version;
+  hit.path = entry.path ?? entry.filePath;
+  hit.snippet = snippet;
+  return hit;
+}
+
+function searchDocs({ query, source }) {
   if (!type.isString(query) || query.trim() === '') {
     throw new Error('searchDocs requires a "query" string.');
   }
-  const manifest = getDocsManifest();
-  if (type.isNone(manifest)) {
-    return [];
+  if (!type.isNone(source) && !docSources.includes(source)) {
+    throw new Error(
+      `Unknown docs source. Received ${JSON.stringify(source)}. Use one of: ${docSources.join(
+        ', '
+      )}.`
+    );
   }
-  const lowerQuery = query.trim().toLowerCase();
-  const titleMatches = [];
-  const contentMatches = [];
-  for (const { doc, content } of getContents({ manifest })) {
-    if (doc.title.toLowerCase().includes(lowerQuery) || doc.slug.includes(lowerQuery)) {
-      titleMatches.push({ ...doc, snippet: content.slice(0, SNIPPET_RADIUS * 2) });
+  let terms = splitSearchTerms({ query });
+  // A query of only short or common words, such as "to a", is searched whole.
+  if (terms.length === 0) {
+    terms = [query.trim().toLowerCase()];
+  }
+  const { entries } = getDocsIndex();
+  const scored = [];
+  for (const entry of entries) {
+    if (!type.isNone(source) && entry.source !== source) {
       continue;
     }
-    const index = content.toLowerCase().indexOf(lowerQuery);
-    if (index !== -1) {
-      const start = Math.max(0, index - SNIPPET_RADIUS);
-      contentMatches.push({
-        ...doc,
-        snippet: content.slice(start, index + lowerQuery.length + SNIPPET_RADIUS),
-      });
+    const content = readDocEntry({ entry });
+    const { score, titleMatched, bodyMatch } = scoreEntry({ entry, content, terms });
+    if (score === 0) {
+      continue;
     }
+    scored.push({
+      score,
+      hit: makeHit({ entry, snippet: makeSnippet({ content, titleMatched, bodyMatch }) }),
+    });
   }
-  return [...titleMatches, ...contentMatches].slice(0, MAX_RESULTS);
+  // Array sort is stable, so entries with equal scores keep index order.
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, MAX_RESULTS).map(({ hit }) => hit);
 }
 
 export default searchDocs;

package/lib/docs/searchDocs.test.mjs

@@ -0,0 +1,100 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'fs';
+import path from 'path';
+
+import getDocsManifest from './getDocsManifest.js';
+import searchDocs from './searchDocs.js';
+
+// The order the substring search gave before terms: title or slug matches,
+// then body matches, each in manifest order.
+function substringOrder(query) {
+  const manifest = getDocsManifest();
+  const lowerQuery = query.toLowerCase();
+  const titleMatches = [];
+  const bodyMatches = [];
+  for (const doc of manifest.docs) {
+    const content = fs.readFileSync(path.join(manifest.contentDir, doc.path), 'utf8');
+    if (doc.title.toLowerCase().includes(lowerQuery) || doc.slug.includes(lowerQuery)) {
+      titleMatches.push(doc.slug);
+    } else if (content.toLowerCase().includes(lowerQuery)) {
+      bodyMatches.push(doc.slug);
+    }
+  }
+  return [...titleMatches, ...bodyMatches].slice(0, 20);
+}
+
+test('searchDocs finds a page from a multi-word query', () => {
+  const results = searchDocs({ query: 'Link action pathParams path parameters' });
+  expect(results[0].slug).toEqual('actions/link');
+});
+
+test('searchDocs ranks entries matching more terms first', () => {
+  const results = searchDocs({ query: 'MongoDB aggregation pipeline' });
+  expect(results[0].slug).toEqual('connections/mongodb');
+});
+
+test('searchDocs keeps the substring order for a single-term query', () => {
+  for (const query of ['SetState', 'modal', 'pathParams']) {
+    expect(searchDocs({ query }).map((hit) => hit.slug)).toEqual(substringOrder(query));
+  }
+});
+
+test('searchDocs leaves out entries matching no term', () => {
+  expect(searchDocs({ query: 'zzqqxx wwvvyy' })).toEqual([]);
+});
+
+test('searchDocs searches the whole query when every term is dropped', () => {
+  const results = searchDocs({ query: 'to a' });
+  expect(results.length).toBeGreaterThan(0);
+  expect(results.map((hit) => hit.slug)).toEqual(substringOrder('to a'));
+});
+
+test('searchDocs hits name their source, package and version', () => {
+  const [hit] = searchDocs({ query: 'SetState' });
+  expect(hit).toEqual(
+    expect.objectContaining({
+      slug: 'actions/setstate',
+      source: 'core',
+      package: '@lowdefy/docs-content',
+      version: getDocsManifest().version,
+      path: 'content/actions/setstate.md',
+    })
+  );
+  expect(hit.snippet.startsWith('# SetState')).toBe(true);
+});
+
+test('searchDocs snippet surrounds the first body match when no title matches', () => {
+  const results = searchDocs({ query: 'placeholders' });
+  const bodyHit = results.find((hit) => !hit.title.toLowerCase().includes('placeholders'));
+  expect(bodyHit.snippet.toLowerCase()).toContain('placeholders');
+});
+
+test('searchDocs source filter narrows hits to that source', () => {
+  expect(searchDocs({ query: 'SetState', source: 'core' }).length).toBeGreaterThan(0);
+  expect(searchDocs({ query: 'SetState', source: 'module' })).toEqual([]);
+});
+
+test('searchDocs throws on an unknown source, naming the sources', () => {
+  expect(() => searchDocs({ query: 'SetState', source: 'blog' })).toThrow(
+    'Unknown docs source. Received "blog". Use one of: core, plugin, local-plugin, module.'
+  );
+});
+
+test('searchDocs throws on an empty query', () => {
+  expect(() => searchDocs({ query: '  ' })).toThrow('requires a "query" string');
+});

package/lib/docs/searchIcons.js

@@ -0,0 +1,90 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+import { defaultIconAliases, getLucideIconNames, loadIconSets } from '@lowdefy/build/dev';
+
+import readBuildArtifact from './readBuildArtifact.js';
+
+const DEFAULT_LIMIT = 30;
+
+let setNamesCache = { key: null, names: [] };
+
+// Installed icon sets are read through the loader the build uses, so search
+// and the build agree. Icons a plugin adds to "lucide" are listed unqualified,
+// like Lucide's own; every other set's names are listed qualified, which
+// always resolve. Cached until the plugin list in the build changes.
+async function getSetNames() {
+  const iconSets = readBuildArtifact({ name: 'customTypesMap.json' })?.iconSets ?? {};
+  const key = JSON.stringify(iconSets);
+  if (setNamesCache.key === key) {
+    return setNamesCache.names;
+  }
+  const sets = await loadIconSets({
+    context: { directories: { server: process.cwd() }, typesMap: { iconSets } },
+  });
+  const lucideNames = new Set(Object.values(getLucideIconNames()).flat());
+  const names = [];
+  Object.entries(sets).forEach(([setId, layers]) => {
+    const setNames = new Set(layers.flatMap((layer) => [...layer.names]));
+    [...setNames].sort().forEach((name) => {
+      if (setId !== 'lucide') {
+        names.push(`${setId}:${name}`);
+      } else if (!lucideNames.has(name)) {
+        names.push(name);
+      }
+    });
+  });
+  setNamesCache = { key, names };
+  return names;
+}
+
+function matchesWords(text, words) {
+  const lowerText = text.toLowerCase();
+  return words.every((word) => lowerText.includes(word));
+}
+
+async function searchIcons({ query, limit = DEFAULT_LIMIT }) {
+  if (!type.isString(query) || query.trim() === '') {
+    throw new Error('searchIcons requires a "query" string.');
+  }
+  const words = query
+    .trim()
+    .toLowerCase()
+    .split(/[\s-]+/);
+  // The dev build writes the full semantic map (built-in, the default icon
+  // set's and theme.icons.aliases). Before the first build only the built-in
+  // names are known.
+  const semantic = readBuildArtifact({ name: 'iconAliases.json' }) ?? defaultIconAliases;
+
+  const semanticResults = Object.entries(semantic)
+    .filter(([name, icon]) => matchesWords(`${name} ${icon}`, words))
+    .map(([name, icon]) => ({ name, icon }));
+  // Canonical Lucide names rank before alias names (Home is an alias of House).
+  const { canonical, aliases } = getLucideIconNames();
+  const iconResults = [...canonical, ...aliases, ...(await getSetNames())]
+    .filter((name) => matchesWords(name, words))
+    .slice(0, limit);
+
+  return {
+    semantic: semanticResults,
+    icons: iconResults,
+    usage:
+      'Use a semantic name from "semantic" (icon: edit, or <i data-icon="edit"></i> in HTML). Otherwise use a Lucide name from "icons" in PascalCase (icon: Receipt). Never invent a name. Qualified names (set:Name) come from installed icon set plugins. Add app-specific semantic names under theme.icons.aliases in lowdefy.yaml.',
+  };
+}
+
+export default searchIcons;