@raystack/chronicle 0.8.0 → 0.9.0

package/dist/cli/index.js

@@ -424,6 +424,15 @@ async function createViteConfig(options) {
       publicAssets: [{ dir: path6.resolve(projectRoot, "public") }],
       output: {
         dir: resolveOutputDir(projectRoot, preset)
+      },
+      experimental: {
+        database: true
+      },
+      database: {
+        default: {
+          connector: "sqlite",
+          options: { name: "chronicle-search" }
+        }
       }
     }
   };
@@ -449,7 +458,7 @@ import chalk from "chalk";
 import { parse } from "yaml";
 
 // src/types/config.ts
-import uniqBy from "lodash/uniqBy.js";
+import { uniqBy } from "lodash-es";
 import { z } from "zod";
 var logoSchema = z.object({
   light: z.string().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",
@@ -23,7 +23,7 @@
     "@biomejs/biome": "^2.3.13",
     "@raystack/tools-config": "0.56.0",
     "@types/hast": "^3.0.4",
-    "@types/lodash": "^4.17.23",
+    "@types/lodash-es": "^4.17.12",
     "@types/mdast": "^4.0.4",
     "@types/mdx": "^2.0.13",
     "@types/node": "^25.1.0",
@@ -59,9 +59,8 @@
     "glob": "^11.0.0",
     "gray-matter": "^4.0.3",
     "h3": "^2.0.1-rc.16",
-    "lodash": "^4.17.23",
+    "lodash-es": "^4.17.23",
     "mermaid": "^11.13.0",
-    "minisearch": "^7.2.0",
     "nitro": "3.0.260311-beta",
     "openapi-types": "^12.1.3",
     "react": "^19.0.0",

package/src/components/ui/search.module.css

@@ -13,6 +13,7 @@
 
 .list {
   max-height: 400px;
+  gap: var(--rs-space-3);
 }
 
 .list :global([cmdk-group-heading]) {
@@ -24,13 +25,14 @@
 }
 
 .item {
-  height: 32px;
+  min-height: 40px;
   padding: var(--rs-space-3);
   gap: var(--rs-space-3);
   border-radius: var(--rs-radius-2);
   cursor: pointer;
 }
 
+
 .item[data-selected="true"] {
   background: var(--rs-color-background-base-primary-hover);
 }
@@ -43,8 +45,9 @@
 
 .resultText {
   display: flex;
-  align-items: center;
-  gap: 8px;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
 }
 
 .headingText {
@@ -68,16 +71,35 @@
 }
 
 .icon {
-  width: 18px;
-  height: 18px;
+  width: 48px;
+  height: 24px;
   color: var(--rs-color-foreground-base-secondary);
   flex-shrink: 0;
 }
 
+.itemContent :global([class*="badge-module"]) {
+  min-width: 48px;
+  justify-content: center;
+}
+
 .item[data-selected="true"] .icon {
   color: var(--rs-color-foreground-accent-primary-hover);
 }
 
+.snippetText {
+  font-size: var(--rs-font-size-mini);
+  line-height: var(--rs-line-height-mini);
+  color: var(--rs-color-foreground-base-tertiary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.matchHighlight {
+  color: var(--rs-color-foreground-accent-primary);
+  font-weight: var(--rs-font-weight-medium);
+}
+
 .pageText :global(mark),
 .headingText :global(mark) {
   background: transparent;

package/src/components/ui/search.tsx

@@ -4,7 +4,7 @@ import {
   MagnifyingGlassIcon
 } from '@heroicons/react/24/outline';
 import { Command, IconButton, Text } from '@raystack/apsara';
-import debounce from 'lodash/debounce';
+import { debounce } from 'lodash-es';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useNavigate } from 'react-router';
 import { MethodBadge } from '@/components/api/method-badge';
@@ -16,6 +16,8 @@ interface SearchResult {
   url: string;
   type: string;
   content: string;
+  match?: 'title' | 'heading' | 'body';
+  snippet?: string;
 }
 
 interface SearchProps {
@@ -121,7 +123,7 @@ export function Search({ classNames }: SearchProps) {
 
       <Command.Dialog open={open} onOpenChange={setOpen}>
         <Command.DialogContent className={styles.dialogContent}>
-          <Command>
+          <Command items={displayResults}>
             <Command.Input
               placeholder='Search'
               leadingIcon={<MagnifyingGlassIcon width={16} height={16} />}
@@ -171,23 +173,17 @@ export function Search({ classNames }: SearchProps) {
                     <div className={styles.itemContent}>
                       {getResultIcon(result)}
                       <div className={styles.resultText}>
-                        {result.type === 'heading' ? (
-                          <>
-                            <Text className={styles.headingText}>
-                              <HighlightedText
-                                html={stripMethod(result.content)}
-                              />
-                            </Text>
-                            <Text className={styles.separator}>-</Text>
-                            <Text className={styles.pageText}>
-                              {getPageTitle(result.url)}
-                            </Text>
-                          </>
-                        ) : (
-                          <Text className={styles.pageText}>
-                            <HighlightedText
-                              html={stripMethod(result.content)}
-                            />
+                        <Text className={styles.pageText}>
+                          <HighlightQuery text={stripMethod(result.content)} query={search} />
+                        </Text>
+                        {result.snippet && result.match === 'heading' && (
+                          <Text className={styles.snippetText}>
+                            # <HighlightQuery text={result.snippet} query={search} />
+                          </Text>
+                        )}
+                        {result.snippet && result.match === 'body' && (
+                          <Text className={styles.snippetText}>
+                            <HighlightQuery text={result.snippet} query={search} />
                           </Text>
                         )}
                       </div>
@@ -236,6 +232,19 @@ function HighlightedText({
   );
 }
 
+function HighlightQuery({ text, query }: { text: string; query: string }) {
+  if (!query) return <>{text}</>;
+  const idx = text.toLowerCase().indexOf(query.toLowerCase());
+  if (idx < 0) return <>{text}</>;
+  return (
+    <>
+      {text.slice(0, idx)}
+      <span className={styles.matchHighlight}>{text.slice(idx, idx + query.length)}</span>
+      {text.slice(idx + query.length)}
+    </>
+  );
+}
+
 function getResultIcon(result: SearchResult): React.ReactNode {
   if (!result.url.startsWith('/apis/')) {
     return result.type === 'page' ? (

package/src/lib/page-context.tsx

@@ -116,7 +116,7 @@ export function PageProvider({
   const fetchPageData = useCallback(async (slug: string[]): Promise<PageData> => {
     const apiPath = slug.length === 0
       ? '/api/page'
-      : `/api/page?slug=${slug.join(',')}`;
+      : `/api/page?slug=${slug.map(s => encodeURIComponent(s)).join(',')}`;
     const res = await fetch(apiPath);
     if (!res.ok) throw new Error(String(res.status));
     return res.json();

package/src/lib/source.ts

@@ -1,3 +1,5 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import { loader } from 'fumadocs-core/source';
 import { flattenTree } from 'fumadocs-core/page-tree';
 import type { Root, Node, Folder } from 'fumadocs-core/page-tree';
@@ -118,14 +120,30 @@ export function invalidate() {
   cachedNavMap = null;
 }
 
+function getFolderPath(node: Folder): string | null {
+  const firstPage = findFirstPage(node);
+  if (!firstPage) return null;
+  const parts = firstPage.url.split('/').filter(Boolean);
+  parts.pop();
+  return '/' + parts.join('/');
+}
+
+function findFirstPage(node: Folder): { url: string } | null {
+  for (const child of node.children) {
+    if (child.type === 'page') return child;
+    if (child.type === 'folder') {
+      const found = findFirstPage(child);
+      if (found) return found;
+    }
+  }
+  return node.index ?? null;
+}
+
 function getOrder(node: Node, pageOrderMap: Map<string, number>, folderOrderMap: Map<string, number>): number | undefined {
   if (node.type === 'page') return pageOrderMap.get(node.url);
   if (node.type === 'folder') {
-    if (node.index) {
-      const fromMeta = folderOrderMap.get(node.index.url);
-      if (fromMeta !== undefined) return fromMeta;
-      return pageOrderMap.get(node.index.url);
-    }
+    const folderPath = getFolderPath(node);
+    if (folderPath) return folderOrderMap.get(folderPath);
   }
   return undefined;
 }
@@ -259,6 +277,35 @@ export function getOriginalPath(page: { data: unknown }): string {
   return ((page.data as Record<string, unknown>)._originalPath as string) ?? '';
 }
 
+export async function getPageSearchContent(page: { data: unknown }): Promise<{ headings: string; body: string }> {
+  const originalPath = getOriginalPath(page);
+  if (!originalPath) return { headings: '', body: '' };
+  try {
+    const contentDir = typeof __CHRONICLE_CONTENT_DIR__ !== 'undefined' ? __CHRONICLE_CONTENT_DIR__ : process.cwd();
+    const filePath = path.resolve(contentDir, originalPath);
+    const raw = await fs.readFile(filePath, 'utf-8');
+    const withoutFrontmatter = raw.replace(/^---[\s\S]*?---/m, '');
+    const headings: string[] = [];
+    const lines: string[] = [];
+    for (const line of withoutFrontmatter.split('\n')) {
+      const headingMatch = line.match(/^#{1,6}\s+(.+)/);
+      if (headingMatch) {
+        headings.push(headingMatch[1]);
+      } else if (!line.startsWith('import ') && !line.startsWith('export ') && !line.startsWith('```')) {
+        const cleaned = line
+          .replace(/<[^>]+>/g, '')
+          .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+          .replace(/[*_~`]+/g, '')
+          .trim();
+        if (cleaned) lines.push(cleaned);
+      }
+    }
+    return { headings: headings.join('\n'), body: lines.join(' ') };
+  } catch {
+    return { headings: '', body: '' };
+  }
+}
+
 interface ReadingTime {
   text: string;
   minutes: number;

package/src/server/api/ready.ts

@@ -0,0 +1,15 @@
+import { defineHandler } from 'nitro';
+import { isSearchReady } from './search';
+
+export default defineHandler(() => {
+  const searchReady = isSearchReady();
+
+  if (!searchReady) {
+    return Response.json(
+      { status: 'not_ready', search: false },
+      { status: 503 },
+    );
+  }
+
+  return Response.json({ status: 'ready', search: true });
+});

package/src/server/api/search.ts

@@ -1,79 +1,129 @@
-import MiniSearch from 'minisearch';
 import { defineHandler, HTTPError } from 'nitro';
+import { useDatabase } from 'nitro/database';
 import type { OpenAPIV3 } from 'openapi-types';
 import { getSpecSlug } from '@/lib/api-routes';
 import { getApiConfigsForVersion, loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
-import { extractFrontmatter, getPagesForVersion } from '@/lib/source';
+import { extractFrontmatter, getPageSearchContent, getPagesForVersion } from '@/lib/source';
 import { LATEST_CONTEXT, type VersionContext } from '@/lib/version-source';
 
 interface SearchDocument {
   id: string;
   url: string;
   title: string;
-  content: string;
+  headings: string;
+  body: string;
   type: 'page' | 'api';
 }
 
-const indexCache = new Map<string, MiniSearch<SearchDocument>>();
-const docsCache = new Map<string, SearchDocument[]>();
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 
-function keyFor(ctx: VersionContext): string {
+const LOCK_FILE = path.join(os.tmpdir(), 'chronicle-search-ready');
+
+export const indexedVersions = new Set<string>();
+let indexPromise: Promise<void> | null = null;
+
+function versionKey(ctx: VersionContext): string {
   return ctx.dir ?? '__latest__';
 }
 
-function createIndex(docs: SearchDocument[]): MiniSearch<SearchDocument> {
-  const index = new MiniSearch<SearchDocument>({
-    fields: ['title', 'content'],
-    storeFields: ['url', 'title', 'type'],
-    searchOptions: {
-      boost: { title: 2 },
-      fuzzy: 0.2,
-      prefix: true
-    }
-  });
-  index.addAll(docs);
-  return index;
+// biome-ignore lint/suspicious/noEmptyBlockStatements: intentional no-op catch
+fs.unlink(LOCK_FILE).catch(() => {});
+
+export function isSearchReady(): boolean {
+  return existsSync(LOCK_FILE);
+}
+
+export async function ensureIndex(ctx: VersionContext) {
+  const key = versionKey(ctx);
+  if (indexedVersions.has(key)) return;
+  if (indexPromise) return indexPromise;
+  indexPromise = buildIndex(ctx, key);
+  await indexPromise;
+  indexPromise = null;
+  await fs.writeFile(LOCK_FILE, new Date().toISOString());
+}
+
+async function buildIndex(ctx: VersionContext, key: string) {
+  // biome-ignore lint/correctness/useHookAtTopLevel: useDatabase is a Nitro DI accessor, not a React hook
+  const db = useDatabase();
+
+  await db.exec('DROP TABLE IF EXISTS search_fts');
+  await db.exec('DROP TABLE IF EXISTS search_docs');
+
+  await db.exec(`CREATE TABLE IF NOT EXISTS search_docs (
+    id TEXT PRIMARY KEY,
+    url TEXT NOT NULL,
+    title TEXT NOT NULL,
+    headings TEXT NOT NULL,
+    body TEXT NOT NULL,
+    type TEXT NOT NULL,
+    version TEXT NOT NULL
+  )`);
+
+  await db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS search_fts USING fts5(
+    title,
+    headings,
+    body,
+    content=search_docs,
+    content_rowid=rowid
+  )`);
+
+  const docs = await buildDocs(ctx);
+  for (const doc of docs) {
+    await db.sql`INSERT INTO search_docs (id, url, title, headings, body, type, version)
+      VALUES (${doc.id}, ${doc.url}, ${doc.title}, ${doc.headings}, ${doc.body}, ${doc.type}, ${key})`;
+  }
+
+  await db.sql`INSERT INTO search_fts (rowid, title, headings, body)
+    SELECT rowid, title, headings, body FROM search_docs WHERE version = ${key}`;
+
+  indexedVersions.add(key);
 }
 
-async function scanContent(ctx: VersionContext): Promise<SearchDocument[]> {
+async function buildDocs(ctx: VersionContext): Promise<SearchDocument[]> {
+  const docs: SearchDocument[] = [];
+
   const pages = await getPagesForVersion(ctx);
-  return pages.map(p => {
+  for (const p of pages) {
     const fm = extractFrontmatter(p);
-    return {
+    const { headings, body } = await getPageSearchContent(p);
+    docs.push({
       id: p.url,
       url: p.url,
       title: fm.title,
-      content: fm.description ?? '',
-      type: 'page' as const
-    };
-  });
-}
+      headings,
+      body: [fm.description ?? '', body].join(' '),
+      type: 'page',
+    });
+  }
 
-async function buildApiDocs(ctx: VersionContext): Promise<SearchDocument[]> {
   const config = loadConfig();
   const apiConfigs = getApiConfigsForVersion(config, ctx.dir);
-  if (!apiConfigs.length) return [];
-
-  const docs: SearchDocument[] = [];
-  const specs = await loadApiSpecs(apiConfigs);
-
-  for (const spec of specs) {
-    const specSlug = getSpecSlug(spec);
-    const paths = spec.document.paths ?? {};
-    for (const [, pathItem] of Object.entries(paths)) {
-      if (!pathItem) continue;
-      for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
-        const op = pathItem[method] as OpenAPIV3.OperationObject | undefined;
-        if (!op?.operationId) continue;
-        const url = `${ctx.urlPrefix}/apis/${specSlug}/${encodeURIComponent(op.operationId)}`;
-        docs.push({
-          id: url,
-          url,
-          title: `${method.toUpperCase()} ${op.summary ?? op.operationId}`,
-          content: op.description ?? '',
-          type: 'api'
-        });
+  if (apiConfigs.length) {
+    const specs = await loadApiSpecs(apiConfigs);
+    for (const spec of specs) {
+      const specSlug = getSpecSlug(spec);
+      const paths = spec.document.paths ?? {};
+      for (const [pathStr, pathItem] of Object.entries(paths)) {
+        if (!pathItem) continue;
+        for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+          const op = pathItem[method] as OpenAPIV3.OperationObject | undefined;
+          if (!op) continue;
+          const opId = op.operationId ?? `${method}_${pathStr.replace(/[/{}\-]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '')}`;
+          const url = `${ctx.urlPrefix}/apis/${specSlug}/${encodeURIComponent(opId)}`;
+          docs.push({
+            id: url,
+            url,
+            title: `${method.toUpperCase()} ${op.summary ?? opId}`,
+            headings: op.summary ?? opId,
+            body: [op.description ?? '', pathStr, method.toUpperCase()].join(' '),
+            type: 'api',
+          });
+        }
       }
     }
   }
@@ -81,27 +131,32 @@ async function buildApiDocs(ctx: VersionContext): Promise<SearchDocument[]> {
   return docs;
 }
 
-async function getDocs(ctx: VersionContext): Promise<SearchDocument[]> {
-  const key = keyFor(ctx);
-  const cached = docsCache.get(key);
-  if (cached) return cached;
-  const [contentDocs, apiDocs] = await Promise.all([
-    scanContent(ctx),
-    buildApiDocs(ctx)
-  ]);
-  const docs = [...contentDocs, ...apiDocs];
-  docsCache.set(key, docs);
-  return docs;
-}
+function findMatch(
+  query: string,
+  title: string,
+  headings: string,
+  body: string,
+): { match: 'title' | 'heading' | 'body'; snippet: string } {
+  if (title.toLowerCase().includes(query)) {
+    return { match: 'title', snippet: title };
+  }
 
-async function getIndex(ctx: VersionContext): Promise<MiniSearch<SearchDocument>> {
-  const key = keyFor(ctx);
-  const cached = indexCache.get(key);
-  if (cached) return cached;
-  const docs = await getDocs(ctx);
-  const index = createIndex(docs);
-  indexCache.set(key, index);
-  return index;
+  const headingList = headings.split('\n').filter(Boolean);
+  for (const h of headingList) {
+    if (h.toLowerCase().includes(query)) {
+      return { match: 'heading', snippet: h };
+    }
+  }
+
+  const idx = body.toLowerCase().indexOf(query);
+  if (idx >= 0) {
+    const start = Math.max(0, idx - 40);
+    const end = Math.min(body.length, idx + query.length + 80);
+    const snippet = (start > 0 ? '...' : '') + body.slice(start, end).trim() + (end < body.length ? '...' : '');
+    return { match: 'body', snippet };
+  }
+
+  return { match: 'title', snippet: title };
 }
 
 function resolveCtx(tag: string | null): VersionContext {
@@ -121,25 +176,44 @@ export default defineHandler(async event => {
   const query = event.url.searchParams.get('query') ?? '';
   const tag = event.url.searchParams.get('tag');
   const ctx = resolveCtx(tag);
-  const index = await getIndex(ctx);
+
+  await ensureIndex(ctx);
+  // biome-ignore lint/correctness/useHookAtTopLevel: useDatabase is a Nitro DI accessor, not a React hook
+  const db = useDatabase();
+  const key = versionKey(ctx);
 
   if (!query) {
-    const docs = await getDocs(ctx);
-    return Response.json(docs
-      .filter(d => d.type === 'page')
-      .slice(0, 8)
-      .map(d => ({
-        id: d.id,
-        url: d.url,
-        type: d.type,
-        content: d.title
-      })));
+    const result = await db.sql`SELECT id, url, title, type FROM search_docs
+      WHERE version = ${key} AND type = 'page'
+      LIMIT 8`;
+    return Response.json((result.rows ?? []).map(r => ({
+      id: r.id,
+      url: r.url,
+      type: r.type,
+      content: r.title,
+    })));
   }
 
-  return Response.json(index.search(query).map(r => ({
-    id: r.id,
-    url: r.url,
-    type: r.type,
-    content: r.title
-  })));
+  const searchTerm = query.split(/\s+/).map(t => `"${t}"*`).join(' ');
+  const result = await db.sql`SELECT s.id, s.url, s.title, s.headings, s.body, s.type,
+      bm25(search_fts, 10.0, 5.0, 1.0) AS score
+    FROM search_fts f
+    JOIN search_docs s ON s.rowid = f.rowid
+    WHERE search_fts MATCH ${searchTerm}
+      AND s.version = ${key}
+    ORDER BY score
+    LIMIT 20`;
+
+  const queryLower = query.toLowerCase();
+  return Response.json((result.rows ?? []).map(r => {
+    const { match, snippet } = findMatch(queryLower, r.title as string, r.headings as string, r.body as string);
+    return {
+      id: r.id,
+      url: r.url,
+      type: r.type,
+      content: r.title,
+      match,
+      snippet,
+    };
+  }));
 });

package/src/server/vite-config.ts

@@ -136,6 +136,15 @@ export async function createViteConfig(
       output: {
         dir: resolveOutputDir(projectRoot, preset),
       },
+      experimental: {
+        database: true,
+      },
+      database: {
+        default: {
+          connector: 'sqlite',
+          options: { name: 'chronicle-search' },
+        },
+      },
     },
   };
 }

package/src/themes/default/Page.module.css

@@ -11,6 +11,10 @@
   max-width: 768px;
 }
 
+.title {
+  margin: 0 0 var(--rs-space-8) 0;
+}
+
 .content {
   line-height: 1.7;
 }

package/src/themes/default/Page.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { Flex } from '@raystack/apsara';
+import { Flex, Headline } from '@raystack/apsara';
 import type { ThemePageProps } from '@/types';
 import styles from './Page.module.css';
 import { Toc } from './Toc';
@@ -9,6 +9,11 @@ export function Page({ page }: ThemePageProps) {
   return (
     <Flex className={styles.page}>
       <article className={styles.article} data-article-content>
+        {page.frontmatter.title && (
+          <Headline size="t2" render={<h1 />} className={styles.title}>
+            {page.frontmatter.title}
+          </Headline>
+        )}
         <div className={styles.content}>{page.content}</div>
       </article>
       <Toc items={page.toc} />

package/src/types/config.ts

@@ -1,4 +1,4 @@
-import uniqBy from 'lodash/uniqBy.js'
+import { uniqBy } from 'lodash-es'
 import { z } from 'zod'
 
 const logoSchema = z.object({