Search Package

@prox-os/search is the shared OS-native search primitives package for Prox OS apps. It defines searchable documents, query contracts, filters, facets, matches, highlights, result previews, recent searches, saved searches, index stats, local search helpers, adapter examples, React primitives, and mock data for UI Workshop.

It is not a search backend, crawler, embedding pipeline, vector database, command palette, notification center, collaboration thread system, file manager, security dashboard, or OS runtime search daemon. Runtime, apps, and future backend packages own indexing, persistence, permission enforcement, semantic search, routing, and execution.

Package Scope

The package provides:

serializable search contracts for apps, routes, commands, actions, documents, notes, editor documents, files, media, map places, data tables, charts, collaboration threads, comments, notifications, reviews, workspaces, workflows, AI sessions, AI messages, security events, developer tools, and system resources;
query, filter, facet, match, highlight, action ref, result, response, recent search, saved search, index stats, adapter, and event types;
helpers for labels, normalization, tokenization, local ranking, filtering, sorting, facets, grouping, highlights, previews, suggestions, and recent or saved search labels;
adapter examples for actions, app manifests, commands, collaboration objects, notifications, documents, resource refs, file-like objects, AI sessions, security events, and workspace resources;
mock data covering OS apps, docs, editor documents, collaboration, reviews, notifications, files, media, map places, data-table cells, AI sessions, security events, workspaces, Founder Suite resources, and developer tooling;
React primitives for search input, search box, panel, result item, grouped result list, highlights, filters, facets, scope picker, sort select, preview, empty/loading states, recent queries, saved searches, and index stats.

Non-Goals

No Elasticsearch, OpenSearch, Meilisearch, Typesense, Algolia, Postgres full-text, vector database, embedding SDK, crawler, or indexer.
No real backend search API.
No browser or OS file-system index.
No command palette replacement. @prox-os/command owns launcher and command execution surfaces.
No notification center replacement. @prox-os/notifications owns attention objects and notification UI.
No collaboration state ownership. @prox-os/collaboration owns threads, comments, reviews, sharing, and presence.
No file manager, security dashboard, activity timeline, or AI answer UI.
No real permission enforcement. Phase 1 can express restricted/redacted results only.
No OS Shell private imports.

Core Concepts

Concept	Type	Responsibility
Search document	`OsSearchDocument`	A normalized OS resource that can be searched.
Query	`OsSearchQuery`	Text, scope, filters, sort, pagination, and inclusion flags.
Filter	`OsSearchFilter`	Field/operator/value predicate for narrowing results.
Facet	`OsSearchFacet`	Counted values for kind, source, workspace, tag, access, or other fields.
Match	`OsSearchMatch`	Field-level match metadata for title, body, tag, metadata, author, path, action, or source.
Highlight	`OsSearchHighlightRange`	Character ranges used by `OsSearchHighlight`.
Result	`OsSearchResult`	Ranked document result with score, matches, preview, status, and action refs.
Response	`OsSearchResponse`	Query output with results, facets, total count, timing, and index id.
Recent search	`OsRecentSearch`	Local history record for a query.
Saved search	`OsSavedSearch`	Named reusable query definition.
Index stats	`OsSearchIndexStats`	Lightweight index health and document count summary.
Adapter	`OsSearchAdapter`	Runtime-agnostic search boundary for local or future backend providers.

The index stats component is named OsSearchIndexStatsCard to avoid a TypeScript export collision with the OsSearchIndexStats data type.

Search Versus Command Palette

Search and Command are related but not the same layer.

Command = searchable launcher entry for actions, apps, routes, docs, and AI intents.
Search = searchable document/resource retrieval with filters, facets, previews, and result actions.

@prox-os/search can index command metadata and expose result action refs. @prox-os/command can consume search providers later. The search package does not render or replace the command palette.

React Primitives

OsSearchInput
OsSearchBox
OsSearchPanel
OsSearchResultItem
OsSearchResultList
OsSearchResultGroup
OsSearchHighlight
OsSearchFilterTabs
OsSearchFacetList
OsSearchScopePicker
OsSearchSortSelect
OsSearchPreview
OsSearchEmptyState
OsSearchLoadingState
OsSearchRecentQueries
OsSavedSearchList
OsSearchIndexStatsCard

Storybook

Open UI Workshop and browse:

Search / Overview
Search / Input
Search / Results
Search / Filters & Facets
Search / Panel
Search / Preview
Search / Recent & Saved
Search / Index Stats
Search / App Resource Search
Search / Collaboration Notification Search
Search / AI Security Workspace Search
Search / Actions Command Integration

The stories use mock documents and the local adapter only. They do not connect to a backend search service, vector search provider, crawler, or OS Shell runtime.

Package Relationships

Package	Relationship
`@prox-os/actions`	Search result action refs can represent open in OS, open new tab, copy link, preview, or run action intent. Search does not execute actions.
`@prox-os/command`	Commands can be indexed as searchable documents. Command palette can later call a search provider, but this package does not render command UX.
`@prox-os/collaboration`	Threads, comments, mentions, and reviews can map to searchable documents. Search does not own collaboration state or UI.
`@prox-os/notifications`	Notification title, body, source, target, actor, and kind can map to searchable documents. Search does not own notification center or preferences.
`@prox-os/forms`	Future advanced filter builders can use form primitives. Phase 1 keeps search lightweight.
`@prox-os/editor`	Editor documents, markdown notes, prompts, and code snippets can map to searchable documents. Search does not implement editors.
Future files	File metadata and file index adapters can feed search documents. Search does not implement a file manager.
Future AI UI	AI sessions, summaries, approvals, and semantic answer UI can consume search contracts later.
Future security UI	Permission-aware result rendering and audit search can use status, access, and target metadata.
Future workspace UI	Workspace-scoped search can use workspace ids, facets, and saved searches.
Future activity	Timeline entries can become searchable documents without turning search into the activity package.

Phase Roadmap

Phase 1: Contracts, Local Adapter, Primitives

TypeScript contracts.
Mock search documents, queries, results, facets, recent searches, saved searches, and index stats.
Local search helper and adapter.
React primitives.
Storybook examples.
Docs.
Adapter examples for actions, app manifests, commands, collaboration, notifications, documents, resources, files, AI, security, and workspaces.
No real backend search.
No embedding or vector search.

Phase 2: Provider Boundary And Local State

Define OsSearchProvider.
Local storage provider for recent and saved searches.
Index update events.
Permission-aware redaction helpers.
Search analytics event contract.

Phase 3: OS Runtime Integration

OS top bar and desktop search panel.
Command palette bridge.
App, window, resource, and workspace scoped search.
Notification, collaboration, activity, and search handoff.

Phase 4: Backend And Semantic Search

Backend search API.
Postgres full-text search.
Meilisearch, Typesense, or Algolia provider evaluation.
Vector search and embeddings.
AI answer over search results.
Per-workspace index routing.
Public community resource search for creator routes.

Acceptance Checklist

Package exports contracts, helpers, adapters, mock data, and React primitives.
Local search returns ranked, filtered, sorted, faceted, highlighted results over mock documents.
UI Workshop exposes all core search stories.
No OS Shell private imports.
No real search service, vector database, embedding SDK, or crawler.
Docs state Search versus Command and Phase 1 boundaries.

Search Package

On this page