boltdocs 3.2.2 → 3.3.0

package/dist/node/index.d.cts

@@ -1,12 +1,46 @@
 
-import { flushCache } from "./cache.cjs";
+import { FileCache, flushCache } from "./cache.cjs";
 import { i as handleVercelFeedback, n as handleWebFeedback, r as handleNetlifyFeedback, t as handleAwsFeedback } from "../index-aWC0KjDF.cjs";
-import { a as BoltdocsThemeConfig, c as PluginLogger, d as PluginTransformMiddleware, f as RouteMeta, i as BoltdocsPlugin, l as PluginMeta, n as defineConfig, o as PluginContext, r as BoltdocsConfig, s as PluginLifecycleHooks, t as resolveConfig, u as PluginStore } from "../config-BpzaPsJj.cjs";
+import { C as StructuredData, _ as PluginServerMiddleware, a as BoltdocsThemeConfig, b as RegisteredVirtualModule, c as ExternalFileRoute, d as JsonLdValue, f as PluginContext, g as PluginMeta, h as PluginLogger, i as BoltdocsExperimentalConfig, l as IPluginLifecycleManager, m as PluginLifecycleHooks, n as defineConfig, o as BoltdocsViewTransitionsConfig, p as PluginHmrEvent, r as BoltdocsConfig, s as DiagnosticRecord, t as resolveConfig, u as JsonLdObject, v as PluginStore, x as RouteMeta, y as PluginTransformMiddleware } from "../config-CTsX_tGM.cjs";
 import { InlineConfig, Plugin } from "vite";
 export * from "@bdocs/unist-utils";
 
 //#region \0rolldown/runtime.js
 //#endregion
+//#region src/node/routes/types.d.ts
+interface DirectoryMeta {
+  title?: string;
+  order?: string[] | number;
+  icon?: string;
+  collapsible?: boolean;
+  collapsed?: boolean;
+  [key: string]: unknown;
+}
+/**
+ * Internal representation of a parsed documentation file before finalizing groups.
+ * Stored in the file cache to avoid re-parsing unchanged files.
+ */
+interface ParsedDocFile {
+  /** The core route metadata without group-level details (inferred later) */
+  route: Omit<RouteMeta, 'group' | 'groupTitle' | 'groupPosition'>;
+  /** The base directory of the file (used to group files together) */
+  relativeDir?: string;
+  /** Whether this file is the index file for its directory group */
+  isGroupIndex: boolean;
+  /** If this is a group index, any specific frontmatter metadata dictating the group's title and position */
+  groupMeta?: {
+    title: string;
+    position?: number;
+    icon?: string;
+  };
+  /** Extracted group position from the directory name if it has a numeric prefix */
+  inferredGroupPosition?: number;
+  /** Extracted tab name from the directory name if it follows the (tab-name) syntax */
+  inferredTab?: string;
+  /** Extracted collection name from the [name] directory syntax */
+  inferredCollection?: string;
+}
+//#endregion
 //#region src/node/plugin/types.d.ts
 /**
  * Configuration options specifically for the Boltdocs Vite plugin.
@@ -14,8 +48,14 @@ export * from "@bdocs/unist-utils";
 interface BoltdocsPluginOptions {
   /** The root directory containing markdown files (default: 'docs') */
   docsDir?: string;
-  /** Enable turbo mode (Sätteri MDX compiler) */
-  turbo?: boolean;
+  /** Project root directory (defaults to cwd) */
+  root?: string;
+  /** Pre-computed routes. When provided, the plugin skips route generation in its config hook. */
+  routes?: RouteMeta[];
+  /** Internal build target flag used to keep client and SSR entry generation isolated. */
+  ssr?: boolean;
+  /** Use Sätteri's disk artifacts. Disabled for Vite serve/dev so HMR uses source MDX. */
+  useCompiledPages?: boolean;
 }
 //#endregion
 //#region src/node/plugin/entry.d.ts
@@ -29,11 +69,89 @@ interface BoltdocsPluginOptions {
  */
 declare function generateEntryCode(options: BoltdocsPluginOptions, config?: BoltdocsConfig): string;
 //#endregion
-//#region src/node/routes/index.d.ts
+//#region src/node/routes/parser/cache.d.ts
 /**
- * Invalidates the global route metadata and clears local state.
+ * Parsed-document cache scoped to one Boltdocs project.
+ *
+ * The old implementation kept one process-wide Map. That was fast, but a
+ * second project in the same process could observe the first project's
+ * parsed documents. Instances are intentionally cheap and are owned by a
+ * RouteCacheContext.
  */
-declare function invalidateRouteCache(): void;
+declare class ParserCache {
+  private readonly memoryCache;
+  private readonly cacheDir;
+  constructor(root?: string, namespace?: string);
+  get(file: string): Promise<ParsedDocFile | null>;
+  set(file: string, data: ParsedDocFile): Promise<void>;
+  invalidate(file: string): void;
+  /**
+   * Clear only the process-local entries.
+   *
+   * Disk shards are versioned and validated by `get()` using the source mtime,
+   * so deleting the whole directory on every route invalidation only creates
+   * unnecessary I/O and forces unchanged files to be parsed again. Stale
+   * shards are harmless and are naturally replaced when their files change.
+   */
+  clear(): void;
+  get size(): number;
+}
+declare namespace ParserCache {
+  const get: (file: string) => Promise<ParsedDocFile | null>;
+  const set: (file: string, data: ParsedDocFile) => Promise<void>;
+  const invalidate: (file: string) => void;
+  const clear: () => void;
+}
+//#endregion
+//#region src/node/routes/cache.d.ts
+interface DirectoryMetaCacheEntry {
+  mtimeMs: number;
+  size: number;
+  content: DirectoryMeta;
+}
+interface RouteDiscoverySnapshot {
+  version: 1;
+  files: string[];
+  directoryMetaFiles: string[];
+  directories: Record<string, number>;
+}
+interface RouteCacheVariant {
+  readonly fingerprint: string;
+  readonly docCache: FileCache<ParsedDocFile>;
+  readonly parserCache: ParserCache;
+  cachedFileList: string[] | null;
+  localizedPathCache: Map<string, string>;
+  cachedNativeDocs: Record<string, any> | null;
+  frontmatterHashes: Map<string, string>;
+  directoryMeta: Record<string, DirectoryMeta> | null;
+  cachedDirectoryMetaFiles: string[] | null;
+  directoryMetaEntries: Map<string, DirectoryMetaCacheEntry>;
+  discoverySnapshot: RouteDiscoverySnapshot | null;
+  discoverySnapshotLoaded: boolean;
+  readonly discoverySnapshotPath: string;
+}
+interface RouteCacheContext {
+  readonly docsDir: string;
+  readonly cacheRoot: string;
+  /** Legacy active cache facade used by HMR/plugin consumers. */
+  docCache: FileCache<ParsedDocFile>;
+  parserCache: ParserCache;
+  cachedFileList: string[] | null;
+  localizedPathCache: Map<string, string>;
+  cachedNativeDocs: Record<string, any> | null;
+  frontmatterHashes: Map<string, string>;
+  directoryMeta: Record<string, DirectoryMeta> | null;
+  cachedDirectoryMetaFiles: string[] | null;
+  readonly variants: Map<string, RouteCacheVariant>;
+  activeVariant: RouteCacheVariant | null;
+  activeGenerations: Map<string, Promise<RouteMeta[]>>;
+  generationEpoch: number;
+  disposed: boolean;
+}
+//#endregion
+//#region src/node/routes/index.d.ts
+/** Invalidates one project's route metadata and parser state. */
+declare function invalidateRouteCache(contextOrDocsDir?: RouteCacheContext | string): void;
 /**
  * Generates the entire route map for the documentation site.
  *
@@ -45,10 +163,64 @@ declare function invalidateRouteCache(): void;
  * @param basePath - The base URL path for the routes (default: '/docs')
  * @returns A promise resolving to an array of RouteMeta objects
  */
-declare function generateRoutes(docsDir: string, config?: BoltdocsConfig, basePath?: string, forceScan?: boolean, turbo?: boolean): Promise<RouteMeta[]>;
+declare function generateRoutes(docsDir: string, config?: BoltdocsConfig, basePath?: string, forceScan?: boolean, cacheContext?: RouteCacheContext, cacheVariant?: RouteCacheVariant): Promise<RouteMeta[]>;
+//#endregion
+//#region src/shared/structured-data.d.ts
+interface WebSiteStructuredDataOptions {
+  name: string;
+  url: string;
+  description?: string;
+  searchUrl?: string;
+}
+interface ArticleStructuredDataOptions {
+  headline: string;
+  url: string;
+  description?: string;
+  datePublished?: string | Date;
+  dateModified?: string | Date;
+  image?: string;
+  author?: string | {
+    name: string;
+    url?: string;
+  };
+}
+interface BreadcrumbStructuredDataItem {
+  name: string;
+  url: string;
+}
+interface StructuredDataFactoryOptions {
+  /** A WebSite graph for the global site identity. */
+  website?: WebSiteStructuredDataOptions;
+  /** An Article graph for the current page or release post. */
+  article?: ArticleStructuredDataOptions;
+  /** A BreadcrumbList graph for the current page hierarchy. */
+  breadcrumbs?: BreadcrumbStructuredDataItem[];
+  /** Additional graph nodes for schema types not covered by the presets. */
+  additional?: JsonLdObject | JsonLdObject[];
+}
+/** Preserve literal JSON-LD types in config files and frontmatter helpers. */
+declare function defineStructuredData<T extends StructuredData>(data: T): T;
+/**
+ * Creates one JSON-LD value from the common website/article/breadcrumb presets.
+ * Single-node input returns an object; multiple nodes return a graph array.
+ */
+declare function createStructuredData(options: StructuredDataFactoryOptions): StructuredData;
+declare function createWebSiteStructuredData(options: WebSiteStructuredDataOptions): JsonLdObject;
+declare function createArticleStructuredData(options: ArticleStructuredDataOptions): JsonLdObject;
+declare function createBreadcrumbStructuredData(items: BreadcrumbStructuredDataItem[]): JsonLdObject;
 //#endregion
 //#region src/node/plugins/plugin-types.d.ts
-interface SecureBoltdocsPlugin {
+interface PluginCssConfig {
+  /** CSS files to inject automatically into entry bundle */
+  cssFiles?: string[];
+  /** Inline CSS strings to inject into HTML <head> */
+  headStyles?: string[];
+  /** PostCSS plugins to append to Vite CSS pipeline */
+  postcssPlugins?: unknown[];
+  /** Vite CSS preprocessor options (e.g. scss, less, stylus) */
+  preprocessorOptions?: Record<string, unknown>;
+}
+interface BoltdocsPlugin {
   name: string;
   enforce?: 'pre' | 'post';
   version?: string;
@@ -58,6 +230,7 @@ interface SecureBoltdocsPlugin {
   vitePlugins?: Plugin[];
   components?: Record<string, string>;
   metadata?: Record<string, unknown>;
+  css?: PluginCssConfig;
   middleware?: PluginTransformMiddleware[];
   hooks?: PluginLifecycleHooks;
 }
@@ -105,10 +278,24 @@ declare class BoltdocsPluginStore implements PluginStore {
 }
 //#endregion
 //#region src/node/plugins/plugin-validator.d.ts
-declare function validatePlugins(plugins: any[], boltdocsVersion: string): SecureBoltdocsPlugin[];
+declare function validatePlugins(plugins: any[], boltdocsVersion: string): BoltdocsPlugin[];
+//#endregion
+//#region src/node/plugins/plugin-context.d.ts
+interface PluginRuntimeState {
+  virtualModuleRegistry: Map<string, RegisteredVirtualModule>;
+  middlewareRegistry: Map<string, PluginTransformMiddleware>;
+  diagnosticRecords: DiagnosticRecord[];
+  diagnosticIdCounter: number;
+  hmrFileHandlers: Map<PluginHmrEvent, Set<(filePath: string) => void | Promise<void>>>;
+  hmrSender: ((event: string, data?: unknown) => void) | null;
+  pluginServerMiddleware: PluginServerMiddleware[];
+  serverStartCallbacks: Array<() => void | Promise<void>>;
+  serverEndCallbacks: Array<() => void | Promise<void>>;
+}
 //#endregion
 //#region src/node/plugins/plugin-lifecycle.d.ts
-declare class PluginLifecycleManager {
+declare function resolvePluginHook(plugin: BoltdocsPlugin, hookName: keyof PluginLifecycleHooks | string): Function | undefined;
+declare class PluginLifecycleManager implements IPluginLifecycleManager {
   private plugins;
   private config;
   private store;
@@ -116,7 +303,10 @@ declare class PluginLifecycleManager {
   private rootDir;
   private routes;
   private outDir;
-  constructor(plugins: SecureBoltdocsPlugin[], config: BoltdocsConfig, docsDir?: string, rootDir?: string, routes?: RouteMeta[], outDir?: string);
+  private runtime;
+  private routeCacheContext;
+  private routeCacheVariant;
+  constructor(plugins: BoltdocsPlugin[], config: BoltdocsConfig, docsDir?: string, rootDir?: string, routes?: RouteMeta[], outDir?: string, runtime?: PluginRuntimeState, routeCacheContext?: RouteCacheContext, routeCacheVariant?: RouteCacheVariant);
   runHook(hookName: keyof PluginLifecycleHooks, ...args: unknown[]): Promise<void>;
   runChain<TParams extends Record<string, unknown>>(hookName: keyof PluginLifecycleHooks, initialParams: TParams): Promise<TParams>;
   /**
@@ -125,6 +315,7 @@ declare class PluginLifecycleManager {
    * hooks or declared statically via `BoltdocsPlugin.middleware` are all
    * collected. Execution respects `__signal: 'skip'` and `__signal: 'break'`.
    */
+  hasHook(hookName: keyof PluginLifecycleHooks | 'transformSource' | 'transformMdx' | 'transformHtml'): boolean;
   runMiddlewareChain<TParams extends Record<string, unknown>>(hookName: 'transformSource' | 'transformMdx' | 'transformHtml', initialParams: TParams): Promise<TParams>;
   private getSortedPlugins;
   private createStep;
@@ -133,8 +324,33 @@ declare class PluginLifecycleManager {
   private createLogger;
 }
 //#endregion
-//#region src/node/plugins/index.d.ts
-declare function createPlugin(plugin: SecureBoltdocsPlugin): SecureBoltdocsPlugin;
+//#region src/node/plugins/define-plugin.d.ts
+type PluginFactory<TOptions = Record<string, unknown>> = (options?: TOptions) => BoltdocsPlugin;
+/**
+ * Creates and defines a Boltdocs plugin with strong TypeScript inference.
+ * Supports both a static plugin object or an options-factory function.
+ *
+ * @example
+ * ```ts
+ * export default definePlugin<MyOptions>((options) => ({
+ *   name: 'my-plugin',
+ *   version: '1.0.0',
+ *   client: {
+ *     slots: { 'header:right': './components/HeaderActions.tsx' },
+ *   },
+ *   hooks: {
+ *     'frontmatter:transform'(ctx, { frontmatter }) {
+ *       return { ...frontmatter, readingTime: 5 }
+ *     },
+ *   },
+ * }))
+ * ```
+ */
+declare function definePlugin<TOptions = Record<string, unknown>>(pluginOrFactory: BoltdocsPlugin | PluginFactory<TOptions>): PluginFactory<TOptions> & ((options?: TOptions) => BoltdocsPlugin);
+/**
+ * Alias for `definePlugin` for backwards compatibility.
+ */
+declare function createPlugin<TOptions = Record<string, unknown>>(pluginOrFactory: BoltdocsPlugin | PluginFactory<TOptions>): BoltdocsPlugin | (PluginFactory<TOptions> & ((options?: TOptions) => BoltdocsPlugin));
 //#endregion
 //#region src/node/feedback/handler.d.ts
 interface FeedbackHandlerOptions {
@@ -168,13 +384,25 @@ declare function normalizePath(p: string): string;
  */
 declare function sanitizeFilename(name: string): string;
 declare namespace index_d_exports {
-  export { BoltdocsConfig, BoltdocsPlugin, BoltdocsPluginOptions, BoltdocsPluginStore, BoltdocsThemeConfig, PluginCompatibilityError, PluginContext, PluginError, PluginHookError, PluginLifecycleHooks, PluginLifecycleManager, PluginLogger, PluginMeta, PluginStore, PluginValidationError, RouteMeta, SecureBoltdocsPlugin, createPlugin, createViteConfig, boltdocs as default, defineConfig, flushCache, generateEntryCode, generateRoutes, handleAwsFeedback, handleFeedback, handleNetlifyFeedback, handleVercelFeedback, handleWebFeedback, invalidateRouteCache, normalizePath, resolveConfig, sanitizeFilename, validatePlugins };
+  export { ArticleStructuredDataOptions, BoltdocsConfig, BoltdocsExperimentalConfig, BoltdocsPlugin, BoltdocsPluginOptions, BoltdocsPluginStore, BoltdocsThemeConfig, BoltdocsViewTransitionsConfig, BreadcrumbStructuredDataItem, CreateViteConfigOptions, ExternalFileRoute, IPluginLifecycleManager, JsonLdObject, JsonLdValue, PluginCompatibilityError, PluginContext, PluginCssConfig, PluginError, PluginFactory, PluginHookError, PluginLifecycleHooks, PluginLifecycleManager, PluginLogger, PluginMeta, PluginStore, PluginValidationError, RouteMeta, StructuredData, StructuredDataFactoryOptions, WebSiteStructuredDataOptions, createArticleStructuredData, createBreadcrumbStructuredData, createPlugin, createStructuredData, createViteConfig, createWebSiteStructuredData, boltdocs as default, defineConfig, definePlugin, defineStructuredData, flushCache, generateEntryCode, generateRoutes, handleAwsFeedback, handleFeedback, handleNetlifyFeedback, handleVercelFeedback, handleWebFeedback, invalidateRouteCache, normalizePath, resolveConfig, resolvePluginHook, sanitizeFilename, validatePlugins };
+}
+interface CreateViteConfigOptions {
+  /** Pre-computed routes. When provided, route generation is skipped. */
+  routes?: RouteMeta[];
+  /** Skip generating project types (they were already generated elsewhere). */
+  skipTypes?: boolean;
+  /** Skip writing the link tree (it was already written elsewhere). */
+  skipLinkTree?: boolean;
+  /** Skip route generation entirely. Routes will be generated lazily by virtual modules. */
+  skipRoutes?: boolean;
+  /** Static asset directory relative to the project root (default: docs/public). */
+  publicDir?: string | false;
 }
 declare function boltdocs(options?: BoltdocsPluginOptions): Promise<Plugin[]>;
 /**
  * Generates the complete Vite configuration for a Boltdocs project.
  * This is used by the Boltdocs CLI to run Vite without a user-defined vite.config.ts.
  */
-declare function createViteConfig(root: string, mode?: 'development' | 'production', preResolvedConfig?: BoltdocsConfig, turbo?: boolean): Promise<InlineConfig>;
+declare function createViteConfig(root: string, mode?: 'development' | 'production', preResolvedConfig?: BoltdocsConfig, options?: CreateViteConfigOptions): Promise<InlineConfig>;
 //#endregion
-export { type BoltdocsConfig, type BoltdocsPlugin, type BoltdocsPluginOptions, BoltdocsPluginStore, type BoltdocsThemeConfig, PluginCompatibilityError, type PluginContext, PluginError, PluginHookError, type PluginLifecycleHooks, PluginLifecycleManager, type PluginLogger, type PluginMeta, type PluginStore, PluginValidationError, type RouteMeta, SecureBoltdocsPlugin, createPlugin, createViteConfig, boltdocs as default, defineConfig, flushCache, generateEntryCode, generateRoutes, handleAwsFeedback, handleFeedback, handleNetlifyFeedback, handleVercelFeedback, handleWebFeedback, invalidateRouteCache, normalizePath, resolveConfig, sanitizeFilename, validatePlugins };
+export { type ArticleStructuredDataOptions, type BoltdocsConfig, type BoltdocsExperimentalConfig, BoltdocsPlugin, type BoltdocsPluginOptions, BoltdocsPluginStore, type BoltdocsThemeConfig, type BoltdocsViewTransitionsConfig, type BreadcrumbStructuredDataItem, CreateViteConfigOptions, type ExternalFileRoute, type IPluginLifecycleManager, type JsonLdObject, type JsonLdValue, PluginCompatibilityError, type PluginContext, PluginCssConfig, PluginError, PluginFactory, PluginHookError, type PluginLifecycleHooks, PluginLifecycleManager, type PluginLogger, type PluginMeta, type PluginStore, PluginValidationError, type RouteMeta, type StructuredData, type StructuredDataFactoryOptions, type WebSiteStructuredDataOptions, createArticleStructuredData, createBreadcrumbStructuredData, createPlugin, createStructuredData, createViteConfig, createWebSiteStructuredData, boltdocs as default, defineConfig, definePlugin, defineStructuredData, flushCache, generateEntryCode, generateRoutes, handleAwsFeedback, handleFeedback, handleNetlifyFeedback, handleVercelFeedback, handleWebFeedback, invalidateRouteCache, normalizePath, resolveConfig, resolvePluginHook, sanitizeFilename, validatePlugins };