@dxos/plugin-search 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/hooks/useGlobalSearch.tsx

@@ -2,14 +2,19 @@
 // Copyright 2023 DXOS.org
 //
 
-import React, { type PropsWithChildren, createContext, useContext, useMemo, useState } from 'react';
+import React, { type PropsWithChildren, createContext, useCallback, useContext, useState } from 'react';
 
 import { raise } from '@dxos/debug';
+import { type Entity } from '@dxos/echo';
+import { GlobalFilterProvider } from '@dxos/react-ui-search';
 
-import { type SearchResult } from '../types';
+import { type SearchResult } from '#types';
 
 import { filterObjectsSync, queryStringToMatch } from './sync';
 
+// Re-export for backward compatibility.
+export { useGlobalFilteredObjects, GlobalFilterProvider } from '@dxos/react-ui-search';
+
 type SearchContextType = {
   match?: RegExp;
   setMatch?: (text?: string) => void;
@@ -17,26 +22,40 @@ type SearchContextType = {
 
 const SearchContext = createContext<SearchContextType>({});
 
+/**
+ * Provider for global search context.
+ * Also provides the GlobalFilterProvider for useGlobalFilteredObjects to work.
+ */
 export const SearchContextProvider = ({ children }: PropsWithChildren) => {
   const [match, setMatch] = useState<RegExp>();
   const handleMatch = (text?: string) => setMatch(queryStringToMatch(text));
-  return <SearchContext.Provider value={{ match, setMatch: handleMatch }}>{children}</SearchContext.Provider>;
+
+  // Provide a filter function for useGlobalFilteredObjects.
+  const filterFn = useCallback(
+    <T extends Entity.Any>(objects: T[]): T[] => {
+      if (!match) {
+        return objects;
+      }
+
+      return filterObjectsSync(objects, match)
+        .filter((result) => result.object)
+        .map((result) => result.object!);
+    },
+    [match],
+  );
+
+  return (
+    <SearchContext.Provider value={{ match, setMatch: handleMatch }}>
+      <GlobalFilterProvider filter={filterFn}>{children}</GlobalFilterProvider>
+    </SearchContext.Provider>
+  );
 };
 
 export const useGlobalSearch = () => {
   return useContext(SearchContext) ?? raise(new Error('Missing SearchContext.'));
 };
 
-export const useGlobalSearchResults = <T extends Record<string, any>>(objects?: T[]): SearchResult[] => {
+export const useGlobalSearchResults = <T extends Entity.Unknown>(objects?: T[]): SearchResult<T>[] => {
   const { match } = useGlobalSearch();
   return objects && match ? filterObjectsSync(objects, match) : [];
 };
-
-export const useGlobalFilteredObjects = <T extends Record<string, any>>(objects?: T[]): T[] => {
-  const { match } = useGlobalSearch();
-  if (!match || !objects) {
-    return objects ?? [];
-  }
-
-  return useMemo(() => filterObjectsSync(objects, match).map((result) => result.object), [objects, match]);
-};

package/src/hooks/useSearchResults.ts

@@ -5,12 +5,13 @@
 import { yieldOrContinue } from 'main-thread-scheduling';
 import { useEffect, useState } from 'react';
 
-import { DataType } from '@dxos/schema';
+import { type Entity, Obj } from '@dxos/echo';
+import { Text } from '@dxos/schema';
 
 // TODO(thure): Deprecate search-sync, move still-relevant utilities elsewhere (here, probably).
 import { mapObjectToTextFields, queryStringToMatch } from './sync';
 
-export const filterObjects = async <T extends Record<string, any>>(
+export const filterObjects = async <T extends Entity.Unknown>(
   objects: T[],
   match?: RegExp,
 ): Promise<Map<T, string[][]>> => {
@@ -18,9 +19,10 @@ export const filterObjects = async <T extends Record<string, any>>(
   if (!match) {
     return result;
   }
+
   await Promise.all(
     objects
-      .filter((object) => !(object instanceof DataType.Text))
+      .filter((object) => !Obj.instanceOf(Text.Text, object))
       .map(async (object) => {
         await yieldOrContinue('interactive');
         const fields = mapObjectToTextFields<T>(object);
@@ -34,10 +36,11 @@ export const filterObjects = async <T extends Record<string, any>>(
           });
       }),
   );
+
   return result;
 };
 
-export const useSearchResults = <T extends Record<string, any>>(
+export const useSearchResults = <T extends Entity.Unknown>(
   queryString?: string,
   objects?: T[],
   delay: number = 400,
@@ -47,14 +50,14 @@ export const useSearchResults = <T extends Record<string, any>>(
 
   useEffect(() => {
     setPending(!!(objects && queryString));
-    const timeoutId = setTimeout(async () => {
+    const timeout = setTimeout(async () => {
       const nextResults =
         objects && queryString ? await filterObjects(objects, queryStringToMatch(queryString)) : new Map();
       setResults(nextResults);
       setPending(false);
     }, delay);
 
-    return () => clearTimeout(timeoutId);
+    return () => clearTimeout(timeout);
   }, [queryString, objects]);
 
   return [pending, results];

package/src/hooks/useWebSearch.ts

@@ -2,44 +2,55 @@
 // Copyright 2025 DXOS.org
 //
 
-import { useState } from 'react';
+import { useCallback, useState } from 'react';
 
 import { EXA_API_KEY } from '@dxos/ai/testing';
-import { Obj } from '@dxos/echo';
-import { type DXN } from '@dxos/keys';
+import { Entity, Type } from '@dxos/echo';
 import { log } from '@dxos/log';
 import { getIconAnnotation } from '@dxos/schema';
-import { Testing } from '@dxos/schema/testing';
+import { TestSchema } from '@dxos/schema/testing';
 
-import { search } from '../search';
-import { type SearchResult } from '../types';
+import { type SearchResult } from '#types';
 
+import { search } from '../search';
 import { getStringProperty } from './sync';
 
-export const useWebSearch = ({ query, context }: { query?: string; context?: string }) => {
+export type UseWebSearchProps = {
+  query?: string;
+  context?: string;
+};
+
+export type UseWebSearch = {
+  update: () => Promise<void>;
+  results: SearchResult[];
+  isLoading: boolean;
+};
+
+/** @deprecated */
+// TODO(burdon): Remove testing deps.
+export const useWebSearch = ({ query, context }: UseWebSearchProps): UseWebSearch => {
   const [results, setResults] = useState<SearchResult[]>([]);
   const [isLoading, setIsLoading] = useState(false);
 
-  const runSearch = async () => {
+  const update = useCallback(async () => {
     try {
       setIsLoading(true);
       log.info('Running web search', { query, context });
       const results = await search({
         query,
         context,
-        schema: [Testing.Project, Testing.Organization, Testing.Contact],
+        types: [TestSchema.Person, TestSchema.Project, TestSchema.Organization], // TODO(burdon): ???
         exaApiKey: EXA_API_KEY,
       });
 
       const mappedResults = results.data.map((result): SearchResult => {
-        const schema = Obj.getSchema(result);
+        const schema = Entity.getType(result);
         return {
           id: result.id,
-          objectType: Obj.getTypename(result) as DXN.String | undefined,
           label: getStringProperty(result, ['name', 'title', 'label']),
           snippet: getStringProperty(result, ['description', 'content', 'website', 'email']),
           object: result,
-          icon: schema?.pipe(getIconAnnotation),
+          icon: schema ? getIconAnnotation(Type.getSchema(schema)) : undefined,
         };
       });
 
@@ -47,7 +58,7 @@ export const useWebSearch = ({ query, context }: { query?: string; context?: str
     } finally {
       setIsLoading(false);
     }
-  };
+  }, [query, context]);
 
-  return { runSearch, results, isLoading };
+  return { update, results, isLoading };
 };

package/src/index.ts

@@ -2,8 +2,8 @@
 // Copyright 2023 DXOS.org
 //
 
+// TODO(wittjosiah): Hooks should not be exported from the plugin package at all.
+//   Either refactor callers to not need them or factor them out to a shared package.
 export * from './hooks';
 export * from './meta';
 export * from './types';
-
-export * from './SearchPlugin';

package/src/meta.ts

@@ -2,16 +2,37 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/keys';
+import { trim } from '@dxos/util';
 
-export const SEARCH_PLUGIN = 'dxos.org/plugin/search';
-export const SEARCH_RESULT = `${SEARCH_PLUGIN}/result`;
-
-export const meta: PluginMeta = {
-  id: SEARCH_PLUGIN,
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.search'),
   name: 'Search',
-  description: 'Search ECHO spaces for content.',
+  author: 'DXOS',
+  description: trim`
+    Full-text search engine for finding content across all spaces and object types in DXOS Composer.
+    The plugin provides a global command-palette style dialog (invoked via the OpenSearch operation)
+    that debounces user input and matches it against every field of every ECHO object in the active
+    space, returning ranked results with field-level match context.
+
+    A persistent SearchArticle panel can be pinned in the deck companion sidebar so the query stays
+    visible while navigating documents. Both surfaces share a SearchContextProvider that drives the
+    GlobalFilterProvider, allowing any view that uses useGlobalFilteredObjects to automatically show
+    only the objects matching the current query.
+
+    Web search is available through the Exa integration: when an API key is configured, the plugin
+    can fetch and rank external web results alongside local objects. The results are structured with
+    URL, title, and snippet fields ready for use in Composer documents.
+
+    All search operations are registered through the standard DXOS operations system and can be
+    wired into keyboard shortcuts, command palettes, and AI assistants via the OperationHandlerSet.
+  `,
   icon: 'ph--magnifying-glass--regular',
+  iconHue: 'rose',
   source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-search',
+  spec: 'PLUGIN.mdl',
   tags: ['labs'],
-};
+});
+
+export const SEARCH_RESULT = `${meta.id}.result`;

package/src/operations/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export const SearchOperationHandlerSet = OperationHandlerSet.lazy(() => import('./open-search'));

package/src/operations/open-search.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+
+import { SEARCH_DIALOG } from '../constants';
+import { SearchOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof SearchOperation.OpenSearch> = SearchOperation.OpenSearch.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      yield* Operation.invoke(LayoutOperation.UpdateDialog, {
+        subject: SEARCH_DIALOG,
+        blockAlign: 'start',
+      });
+    }),
+  ),
+);
+
+export default handler;

package/src/plugin.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const SearchPlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export { SearchOperationHandlerSet } from './operations';

package/src/search/exa.test.ts

@@ -6,8 +6,7 @@ import { describe, test } from 'vitest';
 
 import { EXA_API_KEY } from '@dxos/ai/testing';
 import { log } from '@dxos/log';
-import { Testing } from '@dxos/schema/testing';
-import { trim } from '@dxos/util';
+import { TestSchema } from '@dxos/schema/testing';
 
 import { search } from './exa';
 
@@ -16,7 +15,7 @@ describe.skip('Search', () => {
     test.skip('contacts', { timeout: 60_000 }, async () => {
       const objects = await search({
         query: 'top executives at google',
-        schema: [Testing.Contact],
+        types: [TestSchema.Person],
         exaApiKey: EXA_API_KEY,
       });
 
@@ -26,7 +25,7 @@ describe.skip('Search', () => {
     test.skip('contacts projects and orgs', { timeout: 60_000 }, async () => {
       const objects = await search({
         query: 'top executives at google',
-        schema: [Testing.Contact, Testing.Project, Testing.Organization],
+        types: [TestSchema.Person, TestSchema.Project, TestSchema.Organization],
         exaApiKey: EXA_API_KEY,
       });
 
@@ -36,7 +35,7 @@ describe.skip('Search', () => {
     test('a19z org, projects they invest in and team', { timeout: 60_000 }, async () => {
       const objects = await search({
         query: 'a19z org, projects they invest in and team',
-        schema: [Testing.Project, Testing.Organization, Testing.Contact],
+        types: [TestSchema.Project, TestSchema.Organization, TestSchema.Person],
         exaApiKey: EXA_API_KEY,
       });
 
@@ -46,7 +45,7 @@ describe.skip('Search', () => {
     test('companies building CRDTs', { timeout: 60_000 }, async () => {
       const objects = await search({
         query: 'companies building CRDTs',
-        schema: [Testing.Project, Testing.Organization, Testing.Contact],
+        types: [TestSchema.Project, TestSchema.Organization, TestSchema.Person],
         exaApiKey: EXA_API_KEY,
       });
 
@@ -58,7 +57,7 @@ describe.skip('Search', () => {
     test('composer context-based search', { timeout: 60_000 }, async () => {
       const objects = await search({
         context: COMPOSER_DXOS_DOC,
-        schema: [Testing.Project, Testing.Organization, Testing.Contact],
+        types: [TestSchema.Project, TestSchema.Organization, TestSchema.Person],
         exaApiKey: EXA_API_KEY,
       });
 
@@ -68,7 +67,7 @@ describe.skip('Search', () => {
     test.only('edge architecture', { timeout: 60_000 }, async () => {
       const objects = await search({
         context: EDGE_ARCHITECTURE_DOC,
-        schema: [Testing.Project, Testing.Organization, Testing.Contact],
+        types: [TestSchema.Project, TestSchema.Organization, TestSchema.Person],
         exaApiKey: EXA_API_KEY,
       });
 
@@ -77,8 +76,7 @@ describe.skip('Search', () => {
   });
 });
 
-// TODO(dmaretskyi): Import as txt.
-const COMPOSER_DXOS_DOC = trim`
+const COMPOSER_DXOS_DOC = `
 ![img](https://dxos.network/dxos-logotype-blue.png)
 # Welcome to Composer by DXOS
 
@@ -86,7 +84,7 @@ const COMPOSER_DXOS_DOC = trim`
 
 Composer is an extensible application that includes familiar components such as documents, diagrams, and tables. It leverages DXOS — a full stack framework for building collaborative local-first applications.
 
-With our upcoming SDK, you'll be able to build custom plugins, leverage external APIs and integrate with LLMs. All inside of a private collaborative workspace.
+With our SDK, you'll be able to build custom plugins, leverage external APIs and integrate with LLMs. All inside of a private collaborative workspace.
 
 ## Disclaimer
 

package/src/search/exa.ts

@@ -4,19 +4,21 @@
 
 // ISSUE(burdon): deprecated types: MixedStreamParser => effect
 
-import { Option, Schema, SchemaAST } from 'effect';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
 
-import { Key, Obj } from '@dxos/echo';
+import { type Entity, Key, Obj, type Type } from '@dxos/echo';
 import { isEncodedReference } from '@dxos/echo-protocol';
-import { ReferenceAnnotationId } from '@dxos/echo-schema';
-import { mapAst } from '@dxos/effect';
+import { ReferenceAnnotationId } from '@dxos/echo/Annotation';
+import { SchemaEx } from '@dxos/effect';
 import { deepMapValues, trim } from '@dxos/util';
 
-export type SearchOptions<Schema extends Schema.Schema.AnyNoContext> = {
+export type SearchOptions<T extends Type.AnyEntity> = {
   query?: string;
   // TODO(dmaretskyi): How can we pass this through.
   context?: string;
-  schema: Schema[];
+  types: T[];
   exaApiKey: string;
   liveCrawl?: boolean;
 };
@@ -29,11 +31,12 @@ export type SearchResult<T = unknown> = {
   };
 };
 
-export const search = async <Schema extends Schema.Schema.AnyNoContext>(
-  options: SearchOptions<Schema>,
-): Promise<SearchResult<Schema.Schema.Type<Schema>>> => {
+/** @deprecated Use MixedStreamParser */
+export const search = async <T extends Type.AnyEntity>(
+  options: SearchOptions<T>,
+): Promise<SearchResult<Entity.Unknown>> => {
   throw new Error('Not implemented');
-  // assertArgument(options.query || options.context, 'query or context is required');
+  // assertArgument(options.query || options.context, "query or context", "query or context is required");
   // let contextSearchTerms: readonly string[] = [];
   // if (options.context) {
   //   contextSearchTerms = await getSearchTerms(options.AiService, options.context);
@@ -58,10 +61,10 @@ export const search = async <Schema extends Schema.Schema.AnyNoContext>(
   //   systemPrompt += `\n<search_context>${options.context}</search_context>`;
   // }
   // const result = await getStructuredOutput(options.AiService, {
-  //   model: '@anthropic/claude-3-5-haiku-20241022',
+  //   model: 'ai.claude.model.claude-3-5-haiku-20241022',
   //   systemPrompt,
   //   history: [
-  //     Obj.make(DataType.Message, {
+  //     Obj.make(Message.Message, {
   //       created: new Date().toISOString(),
   //       sender: { role: 'user' },
   //       blocks: context.results.map(
@@ -149,7 +152,7 @@ const DATA_EXTRACTION_INSTRUCTIONS = trim`
 
 // const getSearchTerms = async (AiService: AiServiceClient, context: string) => {
 //   const { terms } = await getStructuredOutput(AiService, {
-//     model: '@anthropic/claude-3-5-haiku-20241022',
+//     model: 'ai.claude.model.claude-3-5-haiku-20241022',
 //     systemPrompt: trim`
 //       You are a search term extraction agent.
 //       Extract the relevant search terms from the context.
@@ -157,7 +160,7 @@ const DATA_EXTRACTION_INSTRUCTIONS = trim`
 //       Prefer own names of people, companies, and projects, technologies, and other entities.
 //     `,
 //     history: [
-//       Obj.make(DataType.Message, {
+//       Obj.make(Message.Message, {
 //         created: new Date().toISOString(),
 //         sender: { role: 'user' },
 //         blocks: [
@@ -178,12 +181,12 @@ const DATA_EXTRACTION_INSTRUCTIONS = trim`
 //   return terms;
 // };
 
-const sanitizeObjects = (entries: { data: any; schema: Schema.Schema.AnyNoContext }[]) => {
+const sanitizeObjects = (entries: { data: any; schema: Type.AnyObj }[]) => {
   const idMap = new Map<string, string>();
 
   return entries
     .map((entry) => {
-      idMap.set(entry.data.id, Key.ObjectId.random());
+      idMap.set(entry.data.id, Key.EntityId.random());
       entry.data.id = idMap.get(entry.data.id);
       return entry;
     })
@@ -193,7 +196,7 @@ const sanitizeObjects = (entries: { data: any; schema: Schema.Schema.AnyNoContex
           const ref = value['/'];
           if (idMap.has(ref)) {
             // TODO(dmaretskyi): Whats the best way to represent a local url.
-            return { '/': `dxn:echo:@:${idMap.get(ref)}` };
+            return { '/': `echo:/${idMap.get(ref)}` };
           } else {
             // Search URIs?
             return { '/': `search:?q=${encodeURIComponent(ref)}` };
@@ -220,8 +223,8 @@ const mapSchemaRefs = (schema: Schema.Schema.AnyNoContext): Schema.Schema.AnyNoC
       return SoftRef.ast;
     }
 
-    return mapAst(ast, go);
+    return SchemaEx.mapAst(ast, go);
   };
 
-  return Schema.make(mapAst(schema.ast, go));
+  return Schema.make(SchemaEx.mapAst(schema.ast, go));
 };

package/src/testing.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// Eager re-export of `SearchPlugin`. See `@dxos/plugin-testing/src/core.ts`
+// for the rationale.
+export * from './SearchPlugin';

package/src/translations.ts

@@ -3,21 +3,22 @@
 //
 
 import { type Resource } from '@dxos/react-ui';
+import { translations as searchTranslations } from '@dxos/react-ui-search/translations';
 
-import { meta } from './meta';
+import { meta } from '#meta';
 
 export const translations = [
+  ...searchTranslations,
   {
     'en-US': {
       [meta.id]: {
-        'plugin name': 'Search',
-        'search action label': 'Search spaces',
-        'search placeholder': 'Search…',
-        'search dialog title': 'Open',
-        'recently closed heading': 'Recently closed',
-        'pending results message': 'Searching…',
-        'empty results message': 'No matching items in your spaces',
-        'search label': 'Search',
+        'plugin.name': 'Search',
+        'search-action.label': 'Search spaces',
+        'search.placeholder': 'Search…',
+        'search-dialog.title': 'Search',
+        'recently-closed.heading': 'Recently closed',
+        'pending-results.message': 'Searching…',
+        'search.label': 'Search',
       },
     },
   },

package/src/types/SearchOperation.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Operation } from '@dxos/compute';
+import { DXN } from '@dxos/keys';
+
+import { meta } from '#meta';
+
+const makeKey = (name: string) => DXN.make(`${meta.id}.operation.${name}`);
+
+export const OpenSearch = Operation.make({
+  meta: { key: makeKey('openSearch'), name: 'Open Search', icon: 'ph--magnifying-glass--regular' },
+  input: Schema.Void,
+  output: Schema.Void,
+});

package/src/types/command-score.d.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+declare module 'command-score' {
+  /**
+   * Scores how well a string matches a query using a fuzzy matching algorithm.
+   * Used by cmdk for its built-in filtering.
+   *
+   * @param string - The string to score against.
+   * @param query - The search query.
+   * @returns A score between 0 and 1, where higher values indicate better matches.
+   */
+  function commandScore(string: string, query: string): number;
+  export default commandScore;
+}

package/src/types/index.ts

@@ -2,5 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './action';
 export type * from './search';
+
+export * as SearchOperation from './SearchOperation';

package/src/types/search.ts

@@ -2,28 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-import type { DXN } from '@dxos/keys';
-
-export type SearchResult = {
-  id: string;
-
-  /**
-   * Type kind: "contact", "project", "org", etc.
-   */
-  type?: string;
-  label?: string;
-  match?: RegExp;
-  snippet?: string;
-
-  /**
-   * Icon id.
-   */
-  icon?: string;
-
-  /**
-   * DXN of the object type.
-   */
-  objectType?: DXN.String;
-
-  object?: any;
-};
+export type { SearchResult } from '@dxos/react-ui-search';

package/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+//
+// Copyright 2026 DXOS.org
+//
+
+declare module '*.mdl?raw' {
+  const content: string;
+  export default content;
+}