@blinkk/root-cms 3.0.2 → 3.0.4

package/dist/core/runtime.d.ts

@@ -0,0 +1,46 @@
+/** @deprecated Use client.ts instead. */
+import { RootConfig } from '@blinkk/root';
+import { Query } from 'firebase-admin/firestore';
+import { LoadTranslationsOptions, LocaleTranslations, TranslationsMap } from './client.js';
+/**
+ * Retrieves a doc from Root.js CMS.
+ * @deprecated Use RootCMSClient.getDoc() instead.
+ */
+export declare function getDoc<T>(rootConfig: RootConfig, collectionId: string, slug: string, options: {
+    mode: 'draft' | 'published';
+}): Promise<T | null>;
+/**
+ * Lists docs from a Root.js CMS collection.
+ * @deprecated Use RootCMSClient.listDocs() instead.
+ */
+export declare function listDocs<T>(rootConfig: RootConfig, collectionId: string, options: {
+    mode: 'draft' | 'published';
+    offset?: number;
+    limit?: number;
+    orderBy?: string;
+    orderByDirection?: 'asc' | 'desc';
+    query?: (query: Query) => Query;
+}): Promise<{
+    docs: T[];
+}>;
+/**
+ * Returns the number of docs in a Root.js CMS collection.
+ * @deprecated Use RootCMSClient.getDocsCount() instead.
+ */
+export declare function numDocs(rootConfig: RootConfig, collectionId: string, options: {
+    mode: 'draft' | 'published';
+    query?: (query: Query) => Query;
+}): Promise<number>;
+/**
+ * Publishes scheduled docs.
+ * @deprecated Use RootCMSClient.publishScheduledDocs() instead.
+ */
+export declare function publishScheduledDocs(rootConfig: RootConfig): Promise<any[]>;
+/**
+ * @deprecated Use `RootCMSClient.loadTranslations()`.
+ */
+export declare function loadTranslations(rootConfig: RootConfig, options?: LoadTranslationsOptions): Promise<TranslationsMap>;
+/**
+ * @deprecated Use `RootCMSClient.loadTranslationsForLocale()`.
+ */
+export declare function loadTranslationsForLocale(rootConfig: RootConfig, locale: string, options?: LoadTranslationsOptions): Promise<LocaleTranslations>;

package/dist/{schema-Db_xODoi.d.ts → core/schema.d.ts}

@@ -1,4 +1,4 @@
-interface CommonFieldProps {
+export interface CommonFieldProps {
     /** The type that defines the structure of the field and its UI component. */
     type: string;
     /** The ID provides a key for the field in the data. */
@@ -17,7 +17,7 @@ interface CommonFieldProps {
     /** Hides just the field label in the CMS UI. */
     hideLabel?: boolean;
 }
-type StringField = CommonFieldProps & {
+export type StringField = CommonFieldProps & {
     type: 'string';
     default?: string;
     translate?: boolean;
@@ -37,18 +37,18 @@ type StringField = CommonFieldProps & {
      */
     autosize?: boolean;
 };
-declare function string(field: Omit<StringField, 'type'>): StringField;
-type NumberField = CommonFieldProps & {
+export declare function string(field: Omit<StringField, 'type'>): StringField;
+export type NumberField = CommonFieldProps & {
     type: 'number';
     default?: number;
 };
-declare function number(field: Omit<NumberField, 'type'>): NumberField;
-type DateField = CommonFieldProps & {
+export declare function number(field: Omit<NumberField, 'type'>): NumberField;
+export type DateField = CommonFieldProps & {
     type: 'date';
     default?: string;
 };
-declare function date(field: Omit<DateField, 'type'>): DateField;
-type DateTimeField = CommonFieldProps & {
+export declare function date(field: Omit<DateField, 'type'>): DateField;
+export type DateTimeField = CommonFieldProps & {
     type: 'datetime';
     default?: string;
     /**
@@ -57,14 +57,14 @@ type DateTimeField = CommonFieldProps & {
      */
     timezone?: string;
 };
-declare function datetime(field: Omit<DateTimeField, 'type'>): DateTimeField;
-type BooleanField = CommonFieldProps & {
+export declare function datetime(field: Omit<DateTimeField, 'type'>): DateTimeField;
+export type BooleanField = CommonFieldProps & {
     type: 'boolean';
     default?: boolean;
     checkboxLabel?: string;
 };
-declare function boolean(field: Omit<BooleanField, 'type'>): BooleanField;
-type SelectField = CommonFieldProps & {
+export declare function boolean(field: Omit<BooleanField, 'type'>): BooleanField;
+export type SelectField = CommonFieldProps & {
     type: 'select';
     default?: string;
     options?: Array<{
@@ -74,15 +74,15 @@ type SelectField = CommonFieldProps & {
     translate?: boolean;
     searchable?: boolean;
 };
-declare function select(field: Omit<SelectField, 'type'>): SelectField;
-type MultiSelectField = Omit<SelectField, 'type'> & {
+export declare function select(field: Omit<SelectField, 'type'>): SelectField;
+export type MultiSelectField = Omit<SelectField, 'type'> & {
     type: 'multiselect';
     /** Set to `true` to allow users to create arbitrary values. */
     creatable?: boolean;
     translate?: boolean;
 };
-declare function multiselect(field: Omit<MultiSelectField, 'type'>): MultiSelectField;
-type ImageField = CommonFieldProps & {
+export declare function multiselect(field: Omit<MultiSelectField, 'type'>): MultiSelectField;
+export type ImageField = CommonFieldProps & {
     type: 'image';
     translate?: boolean;
     /** List of supported exts, e.g. `['.mp4']`. */
@@ -94,8 +94,8 @@ type ImageField = CommonFieldProps & {
     /** Set to `false` to disable the alt text input. */
     alt?: boolean;
 };
-declare function image(field: Omit<ImageField, 'type'>): ImageField;
-type FileField = CommonFieldProps & {
+export declare function image(field: Omit<ImageField, 'type'>): ImageField;
+export type FileField = CommonFieldProps & {
     type: 'file';
     /** List of supported exts, e.g. `['.mp4']`. */
     exts?: string[];
@@ -111,8 +111,8 @@ type FileField = CommonFieldProps & {
     /** Set to `false` to disable the alt text input. */
     alt?: boolean;
 };
-declare function file(field: Omit<FileField, 'type'>): FileField;
-type ObjectField = CommonFieldProps & {
+export declare function file(field: Omit<FileField, 'type'>): FileField;
+export type ObjectField = CommonFieldProps & {
     type: 'object';
     fields: FieldWithId[];
     /** Defaults to "drawer". */
@@ -128,8 +128,8 @@ type ObjectField = CommonFieldProps & {
         inline?: boolean;
     };
 };
-declare function object(field: Omit<ObjectField, 'type'>): ObjectField;
-type ArrayField = CommonFieldProps & {
+export declare function object(field: Omit<ObjectField, 'type'>): ObjectField;
+export type ArrayField = CommonFieldProps & {
     type: 'array';
     default?: any[];
     /**
@@ -161,13 +161,13 @@ type ArrayField = CommonFieldProps & {
      */
     defaultOpen?: boolean;
 };
-declare function array(field: Omit<ArrayField, 'type'>): ArrayField;
+export declare function array(field: Omit<ArrayField, 'type'>): ArrayField;
 /**
  * A schema pattern that is resolved at project load time. This allows schemas
  * to reference other schemas by glob pattern without causing circular import
  * issues, since resolution is deferred until all schemas are loaded.
  */
-interface SchemaPattern {
+export interface SchemaPattern {
     /** Marker to identify this as a schema pattern. */
     _schemaPattern: true;
     /** Glob pattern to match schema files. */
@@ -177,7 +177,7 @@ interface SchemaPattern {
     /** Field IDs to omit from the matched schemas. */
     omitFields?: string[];
 }
-type OneOfField = CommonFieldProps & {
+export type OneOfField = CommonFieldProps & {
     type: 'oneof';
     /**
      * UI variant for the oneOf field.
@@ -195,8 +195,8 @@ type OneOfField = CommonFieldProps & {
      */
     types: Schema[] | string[] | Array<Schema | string> | SchemaPattern;
 };
-declare function oneOf(field: Omit<OneOfField, 'type'>): OneOfField;
-type RichTextField = CommonFieldProps & {
+export declare function oneOf(field: Omit<OneOfField, 'type'>): OneOfField;
+export type RichTextField = CommonFieldProps & {
     type: 'richtext';
     translate?: boolean;
     placeholder?: string;
@@ -210,8 +210,8 @@ type RichTextField = CommonFieldProps & {
     /** Custom inline component definitions to include in the rich text editor. */
     inlineComponents?: Schema[];
 };
-declare function richtext(field: Omit<RichTextField, 'type'>): RichTextField;
-type ReferenceField = CommonFieldProps & {
+export declare function richtext(field: Omit<RichTextField, 'type'>): RichTextField;
+export type ReferenceField = CommonFieldProps & {
     type: 'reference';
     /** List of collection ids the reference can be chosen from. */
     collections?: string[];
@@ -220,8 +220,8 @@ type ReferenceField = CommonFieldProps & {
     /** Label for the button. Defaults to "Select". */
     buttonLabel?: string;
 };
-declare function reference(field: Omit<ReferenceField, 'type'>): ReferenceField;
-type ReferencesField = CommonFieldProps & {
+export declare function reference(field: Omit<ReferenceField, 'type'>): ReferenceField;
+export type ReferencesField = CommonFieldProps & {
     type: 'references';
     /** List of collection ids the references can be chosen from. */
     collections?: string[];
@@ -230,15 +230,15 @@ type ReferencesField = CommonFieldProps & {
     /** Label for the button. Defaults to "Select". */
     buttonLabel?: string;
 };
-declare function references(field: Omit<ReferencesField, 'type'>): ReferencesField;
-type Field = StringField | NumberField | DateField | DateTimeField | BooleanField | SelectField | MultiSelectField | ImageField | FileField | ObjectField | ArrayField | OneOfField | RichTextField | ReferenceField | ReferencesField;
+export declare function references(field: Omit<ReferencesField, 'type'>): ReferencesField;
+export type Field = StringField | NumberField | DateField | DateTimeField | BooleanField | SelectField | MultiSelectField | ImageField | FileField | ObjectField | ArrayField | OneOfField | RichTextField | ReferenceField | ReferencesField;
 /**
  * Similar to {@link Field} but with a required `id`.
  * TODO(stevenle): fix this.
  */
-type FieldWithId = Field;
-type ObjectLikeField = ImageField | FileField | ObjectField | OneOfField | ReferenceField;
-interface SchemaPreset<T = Record<string, any>> {
+export type FieldWithId = Field;
+export type ObjectLikeField = ImageField | FileField | ObjectField | OneOfField | ReferenceField;
+export interface SchemaPreset<T = Record<string, any>> {
     /** Unique identifier for the preset within the schema. */
     id: string;
     /** Display title for the preset. Defaults to the preset id. */
@@ -257,7 +257,7 @@ interface SchemaPreset<T = Record<string, any>> {
      */
     data?: T;
 }
-interface Schema {
+export interface Schema {
     /** The name of the content type. Used as the field key. */
     name: string;
     /** Label to use for UI strings. */
@@ -304,13 +304,13 @@ interface Schema {
         image?: string | string[];
     };
 }
-type SchemaWithTypes = Schema & {
+export type SchemaWithTypes = Schema & {
     /** Reusable type definitions used by the schema, e.g. for oneOf() fields. */
     types?: Record<string, Schema>;
 };
-declare function defineSchema(schema: Schema): Schema;
+export declare function defineSchema(schema: Schema): Schema;
 /** Defines the schema for a collection or reusable component. */
-declare const define: typeof defineSchema;
+export declare const define: typeof defineSchema;
 /**
  * Defines a preset for use within `schema.define({presets: [...]})`. The
  * optional generic parameter `T` constrains the shape of the preset's `data`
@@ -326,10 +326,10 @@ declare const define: typeof defineSchema;
  * });
  * ```
  */
-declare function definePreset<T = Record<string, any>>(preset: SchemaPreset<T>): SchemaPreset<T>;
+export declare function definePreset<T = Record<string, any>>(preset: SchemaPreset<T>): SchemaPreset<T>;
 /** Alias for {@link definePreset}. */
-declare const preset: typeof definePreset;
-type Collection = SchemaWithTypes & {
+export declare const preset: typeof definePreset;
+export type Collection = SchemaWithTypes & {
     /**
      * The ID of the collection. This comes from the schema filename, e.g
      * `<id>.schema.ts`.
@@ -397,12 +397,12 @@ type Collection = SchemaWithTypes & {
         direction?: 'asc' | 'desc';
     }>;
 };
-declare function defineCollection(collection: Omit<Collection, 'id'>): Omit<Collection, 'id'>;
-declare const collection: typeof defineCollection;
+export declare function defineCollection(collection: Omit<Collection, 'id'>): Omit<Collection, 'id'>;
+export declare const collection: typeof defineCollection;
 /**
  * Options for `schema.glob()`.
  */
-interface GlobOptions {
+export interface GlobOptions {
     /** Schema names to exclude from the matched results. */
     exclude?: string[];
     /** Field IDs to omit from the matched schemas. */
@@ -449,57 +449,4 @@ interface GlobOptions {
  * });
  * ```
  */
-declare function glob(pattern: string, options?: GlobOptions): SchemaPattern;
-
-type schema_ArrayField = ArrayField;
-type schema_BooleanField = BooleanField;
-type schema_Collection = Collection;
-type schema_CommonFieldProps = CommonFieldProps;
-type schema_DateField = DateField;
-type schema_DateTimeField = DateTimeField;
-type schema_Field = Field;
-type schema_FieldWithId = FieldWithId;
-type schema_FileField = FileField;
-type schema_GlobOptions = GlobOptions;
-type schema_ImageField = ImageField;
-type schema_MultiSelectField = MultiSelectField;
-type schema_NumberField = NumberField;
-type schema_ObjectField = ObjectField;
-type schema_ObjectLikeField = ObjectLikeField;
-type schema_OneOfField = OneOfField;
-type schema_ReferenceField = ReferenceField;
-type schema_ReferencesField = ReferencesField;
-type schema_RichTextField = RichTextField;
-type schema_Schema = Schema;
-type schema_SchemaPattern = SchemaPattern;
-type schema_SchemaPreset<T = Record<string, any>> = SchemaPreset<T>;
-type schema_SchemaWithTypes = SchemaWithTypes;
-type schema_SelectField = SelectField;
-type schema_StringField = StringField;
-declare const schema_array: typeof array;
-declare const schema_boolean: typeof boolean;
-declare const schema_collection: typeof collection;
-declare const schema_date: typeof date;
-declare const schema_datetime: typeof datetime;
-declare const schema_define: typeof define;
-declare const schema_defineCollection: typeof defineCollection;
-declare const schema_definePreset: typeof definePreset;
-declare const schema_defineSchema: typeof defineSchema;
-declare const schema_file: typeof file;
-declare const schema_glob: typeof glob;
-declare const schema_image: typeof image;
-declare const schema_multiselect: typeof multiselect;
-declare const schema_number: typeof number;
-declare const schema_object: typeof object;
-declare const schema_oneOf: typeof oneOf;
-declare const schema_preset: typeof preset;
-declare const schema_reference: typeof reference;
-declare const schema_references: typeof references;
-declare const schema_richtext: typeof richtext;
-declare const schema_select: typeof select;
-declare const schema_string: typeof string;
-declare namespace schema {
-  export { type schema_ArrayField as ArrayField, type schema_BooleanField as BooleanField, type schema_Collection as Collection, type schema_CommonFieldProps as CommonFieldProps, type schema_DateField as DateField, type schema_DateTimeField as DateTimeField, type schema_Field as Field, type schema_FieldWithId as FieldWithId, type schema_FileField as FileField, type schema_GlobOptions as GlobOptions, type schema_ImageField as ImageField, type schema_MultiSelectField as MultiSelectField, type schema_NumberField as NumberField, type schema_ObjectField as ObjectField, type schema_ObjectLikeField as ObjectLikeField, type schema_OneOfField as OneOfField, type schema_ReferenceField as ReferenceField, type schema_ReferencesField as ReferencesField, type schema_RichTextField as RichTextField, type schema_Schema as Schema, type schema_SchemaPattern as SchemaPattern, type schema_SchemaPreset as SchemaPreset, type schema_SchemaWithTypes as SchemaWithTypes, type schema_SelectField as SelectField, type schema_StringField as StringField, schema_array as array, schema_boolean as boolean, schema_collection as collection, schema_date as date, schema_datetime as datetime, schema_define as define, schema_defineCollection as defineCollection, schema_definePreset as definePreset, schema_defineSchema as defineSchema, schema_file as file, schema_glob as glob, schema_image as image, schema_multiselect as multiselect, schema_number as number, schema_object as object, schema_oneOf as oneOf, schema_preset as preset, schema_reference as reference, schema_references as references, schema_richtext as richtext, schema_select as select, schema_string as string };
-}
-
-export { type Collection as C, type Schema as S, schema as s };
+export declare function glob(pattern: string, options?: GlobOptions): SchemaPattern;

package/dist/core/search-extract.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Pure (no I/O) extraction of searchable text from CMS doc data, guided by the
+ * collection's schema.
+ *
+ * Walks `fields: {...}` recursively and emits one record per leaf "text-bearing"
+ * field. The emitted `deepKey` matches the format used by the doc editor's
+ * deep-link system (see ui/hooks/useDeeplink.tsx) so that clicking a search
+ * result navigates the editor to the originating field.
+ *
+ * Reference for the deepKey format (see ui/components/DocEditor/DocEditor.tsx):
+ * - Top-level field:     fields.<id>
+ * - Nested object field: fields.<id>.<sub>
+ * - Array item field:    fields.<id>.<autokey>.<sub>   (autokeys come from `_array`)
+ * - oneOf field:         fields.<id>.<sub>             (siblings of `_type`)
+ */
+import type { Field, Schema } from './schema.js';
+/** Hard cap for any single extracted text value. */
+export declare const MAX_FIELD_TEXT_CHARS = 2000;
+export interface ExtractedRecord {
+    /** Stable record id: `<docId>#<deepKey>`. */
+    id: string;
+    /** Doc id, e.g. `Pages/foo-bar`. */
+    docId: string;
+    collection: string;
+    slug: string;
+    /** Full deep-link path, e.g. `fields.author.name` or `fields.list.<key>.title`. */
+    deepKey: string;
+    /** Field type, e.g. `string`, `richtext`, `select`. */
+    fieldType: string;
+    /** UI label for the field (falls back to `id`). */
+    fieldLabel: string;
+    /** Extracted plain text, truncated to MAX_FIELD_TEXT_CHARS. */
+    text: string;
+}
+interface EmitContext {
+    docId: string;
+    collection: string;
+    slug: string;
+}
+type EmitFn = (record: ExtractedRecord) => void;
+/** Strip HTML tags and decode common entities from a string. */
+export declare function stripHtml(input: string): string;
+interface RichTextLike {
+    blocks?: Array<{
+        type?: string;
+        data?: any;
+    }>;
+}
+/**
+ * Extracts plain text from a richtext value (EditorJS-shaped).
+ *
+ * Supported block types mirror those rendered in `core/richtext.tsx`:
+ * paragraph, heading, quote, ordered/unordered list, table, html. Unknown or
+ * non-textual blocks (e.g. delimiter, image) contribute nothing.
+ */
+export declare function extractRichText(data: RichTextLike | unknown): string;
+/**
+ * Walks a doc's `fields` against its collection schema and emits one record per
+ * text-bearing leaf field.
+ */
+export declare function walkSchemaFields(fields: Field[], data: any, parentDeepKey: string, ctx: EmitContext, emit: EmitFn): void;
+export interface ExtractDocOptions {
+    collection: string;
+    slug: string;
+    /** Top-level fields object as stored on the doc. */
+    fields: any;
+}
+/** Extracts every searchable record from a single doc. */
+export declare function extractDocRecords(schema: Schema, options: ExtractDocOptions): ExtractedRecord[];
+export {};

package/dist/core/search-index.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Persisted full-text search index for the CMS.
+ *
+ * The index is built from the `Drafts` collection of every doc in the project,
+ * serialized via MiniSearch's `toJSON()`, sharded across Firestore docs (to
+ * stay under the 1 MB per-doc limit), and queried server-side by the
+ * `/cms/api/search.query` endpoint.
+ *
+ * Persistence layout:
+ *   Projects/{projectId}/SearchIndex/_meta        — {lastRun, shardCount, docCount, fieldCount}
+ *   Projects/{projectId}/SearchIndex/_docMap      — {records: {[docId]: recordIds[]}}
+ *   Projects/{projectId}/SearchIndex/shard-0..N   — {shardId, data}  (chunks of toJSON())
+ *
+ * Build modes:
+ *   - `force: false` (cron path) — incremental: discard records for docs whose
+ *     `sys.modifiedAt >= lastRun`, re-extract them, addAll. Reconcile deletions
+ *     by diffing _docMap against the live doc-id set per collection.
+ *   - `force: true` — drop everything and re-index every doc.
+ */
+import { RootConfig } from '@blinkk/root';
+import { Timestamp } from 'firebase-admin/firestore';
+import MiniSearch from 'minisearch';
+import type { CMSSearchIndexConfig } from './plugin.js';
+import type { Schema } from './schema.js';
+import { ExtractedRecord } from './search-extract.js';
+interface IndexableRecord extends ExtractedRecord {
+    /** Per-record boost: 2 for title-like fields, 1 otherwise. */
+    weight: number;
+}
+interface SearchIndexMeta {
+    lastRun: Timestamp;
+    shardCount: number;
+    docCount: number;
+    fieldCount: number;
+    /** How many incremental rebuilds have run since the last vacuum. */
+    runsSinceVacuum?: number;
+}
+export interface SearchHit {
+    id: string;
+    docId: string;
+    collection: string;
+    slug: string;
+    deepKey: string;
+    fieldLabel: string;
+    fieldType: string;
+    text: string;
+    score: number;
+    terms: string[];
+}
+export interface RebuildResult {
+    /** True if a full (force) rebuild was performed. */
+    forced: boolean;
+    /** True if the rebuild short-circuited (no work needed). */
+    skipped: boolean;
+    docCount: number;
+    fieldCount: number;
+    shardCount: number;
+    durationMs: number;
+}
+export interface SearchIndexStatus {
+    lastRun: number | null;
+    docCount: number;
+    fieldCount: number;
+    shardCount: number;
+}
+type DocMap = Record<string, string[]>;
+/**
+ * Normalized form of `CMSSearchIndexConfig`. Empty arrays are treated as
+ * "unset" so the user can defensively pass an empty list without accidentally
+ * excluding everything via `includeCollections: []`.
+ */
+interface ResolvedFilters {
+    includeCollections: Set<string> | null;
+    excludeCollections: Set<string> | null;
+    includeDocIds: Set<string> | null;
+    excludeDocIds: Set<string> | null;
+}
+export declare function resolveSearchIndexFilters(config?: CMSSearchIndexConfig): ResolvedFilters;
+export declare function isCollectionIndexable(filters: ResolvedFilters, collectionId: string): boolean;
+export declare function isDocIndexable(filters: ResolvedFilters, docId: string): boolean;
+interface CachedIndex {
+    index: MiniSearch;
+    meta: SearchIndexMeta;
+    docMap: DocMap;
+}
+export declare function isTitleyDeepKey(deepKey: string): boolean;
+export declare function withWeight(rec: ExtractedRecord): IndexableRecord;
+/**
+ * Loader for a collection's schema. Pluggable so callers can provide a
+ * dev-mode loader (Vite SSR) and prod uses the default (`dist/...json`).
+ */
+export type LoadSchemaFn = (collectionId: string) => Promise<Schema | null>;
+export declare class SearchIndexService {
+    private readonly rootConfig;
+    private readonly projectId;
+    private readonly db;
+    private readonly loadSchema;
+    private readonly filters;
+    private cached;
+    constructor(rootConfig: RootConfig, loadSchema?: LoadSchemaFn, filtersOverride?: CMSSearchIndexConfig);
+    /** Returns true if the given collection passes the include/exclude filter. */
+    isCollectionIndexable(collectionId: string): boolean;
+    /**
+     * Returns true if the given doc id passes the include/exclude filter (and
+     * its collection is itself indexable). Doc ids are `<collectionId>/<slug>`.
+     */
+    isDocIndexable(docId: string): boolean;
+    /** Returns the MiniSearch options used by both writers and readers. */
+    static getMiniSearchOptions(): {
+        fields: string[];
+        storeFields: string[];
+        searchOptions: {
+            boost: {
+                fieldLabel: number;
+            };
+            prefix: boolean;
+            fuzzy: number;
+        };
+    };
+    private indexDocPath;
+    private indexCollectionPath;
+    /**
+     * Lists collection ids by globbing `<rootDir>/collections/*.schema.ts`,
+     * filtered by the include/exclude config.
+     */
+    listCollectionIds(): Promise<string[]>;
+    /**
+     * Default schema loader: reads `dist/collections/<id>.schema.json`. These
+     * files are produced by the CMS plugin's `preBuild` hook during a real
+     * `root build`. In dev there is no JSON file on disk, so callers should
+     * pass a dev-aware `loadSchema` callback to the constructor (the API
+     * endpoints do this — they delegate to the same Vite SSR path used by
+     * `/cms/api/collection.get`).
+     */
+    private loadCollectionSchemaFromDist;
+    private readMeta;
+    private readDocMap;
+    /** Reads all shard docs and returns the concatenated MiniSearch JSON string. */
+    private readShards;
+    /** Writes shards, _docMap, _meta in one batched commit. */
+    private writeIndex;
+    /** Drops every doc under the SearchIndex subcollection. */
+    private wipeIndex;
+    /**
+     * Lists the full set of live (collection, slug, doc) tuples for `Drafts`,
+     * filtered by the include/exclude config.
+     */
+    private listAllDocs;
+    /**
+     * Lists docs modified since `lastRun` across every collection, filtered by
+     * the include/exclude config.
+     */
+    private listChangedDocs;
+    /**
+     * Returns true when no docs have been modified since `lastRun` AND no
+     * deletions are pending (i.e. the doc-id set in `_docMap` matches the live
+     * doc-id set across all collections).
+     */
+    hasChangesSince(lastRun: Timestamp, docMap?: DocMap | null): Promise<boolean>;
+    /** Orchestrates a rebuild (incremental by default; full when `force: true`). */
+    rebuildIndex(opts?: {
+        force?: boolean;
+    }): Promise<RebuildResult>;
+    private fullRebuild;
+    private incrementalRebuild;
+    /**
+     * Returns the cached MiniSearch index, loading it from Firestore if
+     * necessary. The cache is keyed off `meta.lastRun` and survives across
+     * requests in the same process.
+     */
+    getIndex(): Promise<CachedIndex | null>;
+    /** Runs a query against the loaded index. */
+    search(q: string, options?: {
+        limit?: number;
+    }): Promise<{
+        hits: SearchHit[];
+        meta: SearchIndexStatus;
+    }>;
+    /** Lightweight metadata read for status endpoints / settings UI. */
+    getStatus(): Promise<SearchIndexStatus>;
+}
+export {};

package/dist/core/search-query.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Google-style query parsing and execution for the CMS search index.
+ *
+ * The CMS spotlight passes raw user input straight through to MiniSearch, which
+ * means quotes, leading dashes, and multiple words all get tokenized the same
+ * way (fuzzy + prefix on every term, OR-combined). That produces noisy results
+ * — typing `homepage hero` returns every doc containing `homepage` *or* a
+ * fuzzy/prefix match for `hero`.
+ *
+ * This module preprocesses the query string into structured parts and runs
+ * each part with the appropriate MiniSearch options:
+ *
+ *   - `"exact phrase"`  — must appear verbatim (token-aligned) in the doc;
+ *                         fuzzy + prefix disabled.
+ *   - `bare term`       — fuzzy + prefix allowed (existing behavior).
+ *   - `-foo` / `-"x y"` — must NOT appear in matching docs.
+ *
+ * Multiple parts are AND-combined so adding more terms narrows results, just
+ * like Google.
+ */
+import MiniSearch, { SearchResult } from 'minisearch';
+/** Structured form of a user query string. */
+export interface ParsedQuery {
+    /** Quoted phrases that must appear verbatim (token-aligned). */
+    phrases: string[];
+    /** Free-form terms; fuzzy + prefix matching applies. */
+    terms: string[];
+    /** Bare terms that must NOT appear in matching docs. */
+    excluded: string[];
+    /** Quoted phrases that must NOT appear in matching docs. */
+    excludedPhrases: string[];
+}
+/**
+ * Splits a Google-style query string into phrases / terms / exclusions.
+ *
+ * Examples:
+ *   `foo "bar baz" -qux`   ->  terms=[foo], phrases=[bar baz], excluded=[qux]
+ *   `"exact phrase only"`  ->  phrases=[exact phrase only]
+ *   `-"forbidden phrase"`  ->  excludedPhrases=[forbidden phrase]
+ *
+ * Notes:
+ *   - Smart quotes (U+201C / U+201D / etc.) are normalized to straight `"`.
+ *   - An unclosed quote is treated as if closed at end-of-input (matches
+ *     Google's behavior — the rest of the query becomes a single phrase).
+ *   - Empty or whitespace-only quotes (`""`, `"  "`) are skipped.
+ *   - A leading `-` only marks exclusion when followed by a non-whitespace
+ *     character; standalone `-` is dropped.
+ */
+export declare function parseQuery(input: string): ParsedQuery;
+/**
+ * Returns true if `phrase` appears in `text` as a contiguous run of word
+ * tokens. Punctuation between tokens is ignored, but token boundaries are
+ * required (so `foo bar` does NOT match `foobar`).
+ */
+export declare function containsPhrase(text: string, phrase: string): boolean;
+/** True if this parsed query carries no positive constraints. */
+export declare function isEmptyQuery(parsed: ParsedQuery): boolean;
+/**
+ * Runs a parsed query against a MiniSearch index using Google-style semantics:
+ *   - phrases match as exact contiguous word runs (no fuzzy / no prefix);
+ *   - free terms keep the index's default fuzzy + prefix behavior;
+ *   - all positive parts are AND-combined (a doc must satisfy each one);
+ *   - excluded terms / phrases remove docs from the result.
+ *
+ * Per-record scores from each part are summed, so a doc that matches more
+ * constraints ranks above one that matches fewer.
+ */
+export declare function executeQuery(index: MiniSearch, parsed: ParsedQuery): SearchResult[];