boltdocs 3.1.0 → 3.2.2

package/dist/{shiki-adapter-l2kEP5rn.d.cts → config-xtS0ZkMm.d.mts}

@@ -1,8 +1,6 @@
 
 import { Plugin } from "vite";
-import * as _$shiki from "shiki";
-import { CodeToHastOptions } from "shiki";
-
+import * as _$http from "http";
 //#region src/shared/types.d.ts
 /**
  * Metadata representing a single documentation route.
@@ -177,6 +175,43 @@ interface BoltdocsVersionConfig {
   label: string;
   path: string;
 }
+/**
+ * Configuration for content collections (e.g. blog posts, changelog)
+ * declared in `boltdocs.config.ts`. Each entry maps a directory name
+ * (e.g. `[blog]`) to its display + ordering settings.
+ */
+interface BoltdocsCollectionsConfig {
+  /**
+   * Map of collection id (matches the bracketed directory name) to
+   * its display label. Falls back to the id when a label is missing.
+   */
+  labels?: Record<string, string | Record<string, string>>;
+  /**
+   * Map of collection id to a numeric position used for sidebar ordering.
+   * Collections with no explicit position are sorted last.
+   */
+  positions?: Record<string, number>;
+  /**
+   * Items-per-page for paginated collection routes (e.g. blog indexes).
+   * Falls back to the framework default (10) when omitted.
+   */
+  postsPerPage?: number;
+  /**
+   * Default collection ID used by collection routing when no collection
+   * is explicitly referenced. Defaults to `'blog'`.
+   */
+  defaultCollection?: string;
+  /**
+   * Date format string for rendering post dates in listing pages.
+   * Defaults to `'MMMM dd, yyyy'`.
+   */
+  dateFormat?: string;
+  /**
+   * Field used to sort posts within a collection.
+   * Defaults to `'date'`.
+   */
+  sortBy?: 'date' | 'title' | 'sidebarPosition';
+}
 /**
  * Configuration for documentation versioning.
  */
@@ -204,6 +239,129 @@ interface PluginContext {
   readonly rootDir: string;
   readonly outDir: string;
   readonly routes: RouteMeta[];
+  /** Namespaced cache helpers bound to the core's cache machinery. */
+  readonly caches: PluginCachesAPI;
+  /** Structured diagnostics channel; reports can be drained via `list()`. */
+  readonly diagnostics: PluginDiagnosticsAPI;
+  /** Helpers for resolving paths inside the workspace safely. */
+  readonly paths: PluginPathsAPI;
+  /** Declare virtual modules the core should expose to Vite. */
+  readonly virtualModules: PluginVirtualModulesAPI;
+  /** Register and query transform middleware at runtime. */
+  readonly middleware: PluginMiddlewareAPI;
+  /**
+   * Hook into dev-server file watching and send custom HMR events
+   * to connected clients.
+   */
+  readonly hmr: PluginHmrAPI;
+  /**
+   * Register HTTP middleware and server lifecycle hooks without
+   * writing a Vite plugin.
+   */
+  readonly server: PluginServerAPI;
+}
+/**
+ * Functional cache helpers exposed through `PluginContext.caches`.
+ *
+ * Plugin authors do not get a reference to the raw `TransformCache` /
+ * `FileCache` instances — those stay encapsulated in core. The methods
+ * returned here are bound to namespaced keys so two plugins cannot
+ * collide.
+ */
+interface PluginCachesAPI {
+  /** Sharded, hash-keyed cache. One namespace per plugin recommended. */
+  transform(namespace: string): PluginTransformCacheAPI;
+  /** Routes cache wrapper around the parsed-doc cache. */
+  routes: PluginRoutesCacheAPI;
+  /** In-memory LRU cache keyed by namespace + plugin-supplied key. */
+  memory<V = unknown>(namespace: string, opts?: {
+    max?: number;
+    ttl?: number;
+  }): PluginMemoryCacheAPI<V>;
+}
+interface PluginTransformCacheAPI {
+  /** Async read — first call may warm from disk if the entry was evicted. */
+  get(key: string): Promise<string | null>;
+  /** Synchronous write that batches a background disk flush. */
+  set(key: string, value: string): void;
+  /** Force-flush background writes. Call before measuring disk state. */
+  flush(): Promise<void>;
+}
+interface PluginRoutesCacheAPI {
+  /** Read a parsed `RouteMeta` (and its private `_content` blob) by abs file path. */
+  get(filePath: string): RouteMeta | null;
+  /** Write a parsed route entry. Caller assumptions match `docCache.set`. */
+  set(filePath: string, route: RouteMeta): void;
+  /** Invalidate one route. Use when content changes. */
+  invalidate(filePath: string): void;
+  /** Clear every cached route. Use when the directory layout changes. */
+  invalidateAll(): void;
+}
+interface PluginMemoryCacheAPI<V> {
+  get(key: string): V | undefined;
+  set(key: string, value: V): void;
+  has(key: string): boolean;
+}
+/**
+ * Plugin diagnostics API.
+ *
+ * Plugins push structured records instead of spamming the logger; downstream
+ * tools (dev-server overlay, CI reporters, IDE plugins) drain the queue via
+ * `list()`.
+ */
+interface DiagnosticRecord {
+  readonly id: number;
+  readonly severity: 'info' | 'warn' | 'error';
+  readonly code: string;
+  readonly message: string;
+  readonly pluginName: string;
+  readonly filePath?: string;
+  readonly routePath?: string;
+  readonly time: Date;
+}
+interface PluginDiagnosticsAPI {
+  report(severity: DiagnosticRecord['severity'], code: string, message: string, where?: {
+    filePath?: string;
+    routePath?: string;
+  }): void;
+  list(): readonly DiagnosticRecord[];
+  clear(): void;
+}
+/**
+ * Path-resolution helpers exposed through `PluginContext.paths`.
+ *
+ * Both `resolveDocs` and `resolveAsset` validate the resulting path against
+ * the workspace boundary and reject any segment that resolves outside the
+ * docs / project root directories.
+ */
+interface PluginPathsAPI {
+  resolveDocs(...parts: string[]): string;
+  resolveAsset(...parts: string[]): string;
+  /**
+   * Build a `file://` URL for an absolute path inside the workspace.
+   * Useful for `new URL(import.meta.url)` replacements and image srcsets.
+   */
+  safeFileURL(absFilePath: string): string;
+}
+/**
+ * Plugin virtual-modules registration.
+ *
+ * Plugins call `add(id, loader)` to expose a `virtual:<plugin>/<id>` module
+ * to Vite without having to author a full Vite plugin. The loader returns
+ * the module source code as a string; the core wraps it in the right
+ * `resolveId`/`load` plumbing at Vite build time.
+ */
+interface RegisteredVirtualModule {
+  readonly id: string;
+  readonly eager: boolean;
+  readonly loader: () => string | Promise<string>;
+}
+interface PluginVirtualModulesAPI {
+  add(id: string, loader: () => string | Promise<string>, opts?: {
+    eager?: boolean;
+  }): void;
+  has(id: string): boolean;
+  list(): readonly RegisteredVirtualModule[];
 }
 /**
  * Logger interface for plugin logging.
@@ -230,6 +388,152 @@ interface PluginMeta {
   version?: string;
   boltdocsVersion?: string;
 }
+/**
+ * Chain control signal returned by transform hooks. Use with `__signal` in
+ * the return value to influence the middleware chain:
+ *
+ * - `'skip'`: stop processing this hook for the current file (remaining
+ *   plugins in the chain still run).
+ * - `'break'`: stop the entire chain immediately — no further plugin's
+ *   transform hooks run for this file.
+ *
+ * @example
+ * ```ts
+ * transformMdx: async (_ctx, { code }) => ({
+ *   code: code.replace(/foo/g, 'bar'),
+ *   __signal: 'skip',   // skip remaining plugins
+ * })
+ * ```
+ */
+type ChainSignal = 'skip' | 'break';
+/**
+ * Returned by a transform hook that wants to signal the chain. The `__signal`
+ * field is optional — most hooks will just return `{ code: string }` and the
+ * chain continues normally. When `__signal` is present, `runChain` reacts:
+ *
+ * - `'skip'` continues with the next plugin, but passes the **original params**
+ *   (the output of this hook is discarded).
+ * - `'break'` stops the chain immediately.
+ *
+ * @template T The params shape (e.g. `{ code: string; filePath: string }`).
+ */
+type TransformResult<T> = T & {
+  __signal?: ChainSignal;
+};
+/**
+ * Enriched params passed to `transformSource` and `transformMdx`. The `code`
+ * and `filePath` fields are always present. The optional `frontmatter` and
+ * `route` fields are populated when available (they are `undefined` in the
+ * early pipeline where frontmatter hasn't been parsed yet).
+ */
+interface TransformSourceParams {
+  /** The raw or compiled code (source before MDX / JS after MDX). */
+  code: string;
+  /** Absolute file path of the source document. */
+  filePath: string;
+  /** Parsed frontmatter, if available. `undefined` in very early pipeline. */
+  frontmatter?: Record<string, unknown>;
+}
+/**
+ * Enriched params passed to `transformHtml`. The `html` and `path` fields
+ * are always present. The optional `route` carries the generated `RouteMeta`
+ * for richer context (locale, version, collection, etc.).
+ */
+interface TransformHtmlParams {
+  /** The rendered HTML string for this page. */
+  html: string;
+  /** The route path (e.g. `/docs/guides/start`). */
+  path: string;
+  /** The route metadata for the page, if available. */
+  route?: RouteMeta;
+}
+/**
+ * Plugin transform middleware. Each middleware runs in the transform
+ * pipeline alongside lifecycle hooks. The `name` field is optional —
+ * when omitted, the owning plugin's name is used as context.
+ * Middleware runs in `enforce` order (pre → normal → post) and supports
+ * `__signal: 'skip'` / `__signal: 'break'` for chain control.
+ */
+interface PluginTransformMiddleware {
+  /** Optional name. Defaults to the owning plugin's name for diagnostics. */
+  name?: string;
+  enforce?: 'pre' | 'post';
+  transformSource?: (ctx: PluginContext, params: TransformSourceParams) => TransformResult<{
+    code: string;
+  }> | Promise<TransformResult<{
+    code: string;
+  }>>;
+  transformMdx?: (ctx: PluginContext, params: TransformSourceParams) => TransformResult<{
+    code: string;
+  }> | Promise<TransformResult<{
+    code: string;
+  }>>;
+  transformHtml?: (ctx: PluginContext, params: TransformHtmlParams) => TransformResult<{
+    html: string;
+  }> | Promise<TransformResult<{
+    html: string;
+  }>>;
+}
+/**
+ * Plugin middleware registry API exposed through `PluginContext.middleware`.
+ * Plugins can register named middleware entries from lifecycle hooks.
+ */
+interface PluginMiddlewareAPI {
+  add(middleware: PluginTransformMiddleware): void;
+  remove(name: string): void;
+  has(name: string): boolean;
+  list(): readonly PluginTransformMiddleware[];
+}
+/**
+ * HMR event types plugins can listen to.
+ */
+type PluginHmrEvent = 'add' | 'change' | 'unlink';
+/**
+ * Plugin HMR API — hook into file-watching events and send custom
+ * HMR messages to connected clients.
+ */
+interface PluginHmrAPI {
+  /**
+   * Register a callback for file events scoped to the docs directory.
+   * The callback receives the normalized file path and event type.
+   */
+  onFileEvent(eventType: PluginHmrEvent, handler: (filePath: string) => void | Promise<void>): void;
+  /** Shorthand for `onFileEvent('add', handler)`. */
+  onFileAdd(handler: (filePath: string) => void | Promise<void>): void;
+  /** Shorthand for `onFileEvent('change', handler)`. */
+  onFileChange(handler: (filePath: string) => void | Promise<void>): void;
+  /** Shorthand for `onFileEvent('unlink', handler)`. */
+  onFileUnlink(handler: (filePath: string) => void | Promise<void>): void;
+  /**
+   * Send a custom HMR event to all connected clients.
+   * The client can listen with `import.meta.hot.on('boltdocs:plugin:<name>', ...)`.
+   */
+  send(event: string, data?: unknown): void;
+}
+/**
+ * Plugin Server API — register HTTP middleware and lifecycle hooks
+ * for the dev server and preview server, without writing a Vite plugin.
+ */
+interface PluginServerAPI {
+  /**
+   * Register a Connect-style middleware function.
+   * Runs on both dev and preview servers.
+   */
+  use(middleware: PluginServerMiddleware): void;
+  /**
+   * Register a middleware scoped to a specific path prefix.
+   * Only requests starting with `path` trigger the handler.
+   */
+  useAt(path: string, handler: PluginServerMiddleware): void;
+  /** Called when the dev/preview server starts (once per process). */
+  onStart(callback: () => void | Promise<void>): void;
+  /** Called when the server shuts down (cleanup). */
+  onEnd(callback: () => void | Promise<void>): void;
+}
+/**
+ * Connect-style middleware signature.
+ */
+type PluginServerMiddleware = (req: _$http.IncomingMessage, res: _$http.ServerResponse, next: (err?: unknown) => void) => void | Promise<void>;
 /**
  * Plugin lifecycle hooks with full type safety.
  */
@@ -239,30 +543,21 @@ interface PluginLifecycleHooks {
   beforeDev?: (ctx: PluginContext) => Promise<void> | void;
   afterDev?: (ctx: PluginContext) => Promise<void> | void;
   buildEnd?: (ctx: PluginContext) => Promise<void> | void;
-  transformSource?: (ctx: PluginContext, params: {
-    code: string;
-    filePath: string;
-  }) => Promise<{
-    code: string;
-  }> | {
+  transformSource?: (ctx: PluginContext, params: TransformSourceParams) => TransformResult<{
     code: string;
-  };
-  transformMdx?: (ctx: PluginContext, params: {
+  }> | Promise<TransformResult<{
     code: string;
-    filePath: string;
-  }) => Promise<{
+  }>>;
+  transformMdx?: (ctx: PluginContext, params: TransformSourceParams) => TransformResult<{
     code: string;
-  }> | {
+  }> | Promise<TransformResult<{
     code: string;
-  };
-  transformHtml?: (ctx: PluginContext, params: {
-    html: string;
-    path: string;
-  }) => Promise<{
+  }>>;
+  transformHtml?: (ctx: PluginContext, params: TransformHtmlParams) => TransformResult<{
     html: string;
-  }> | {
+  }> | Promise<TransformResult<{
     html: string;
-  };
+  }>>;
 }
 /**
  * MDX processor configuration.
@@ -286,22 +581,19 @@ interface BoltdocsPlugin {
   rehypePlugins?: unknown[];
   vitePlugins?: Plugin[];
   components?: Record<string, string>;
+  /** Optional runtime metadata exposed to client via useConfig().plugins[].metadata */
+  metadata?: Record<string, unknown>;
+  /** Declarative transform middleware entries. */
+  middleware?: PluginTransformMiddleware[];
   /** Lifecycle hooks with full type safety */
   hooks?: PluginLifecycleHooks;
 }
 /**
- * Configuration for the collections (blog) feature.
  */
-interface BoltdocsCollectionsConfig {
-  /** Number of posts per page in collection listing pages. Defaults to 10. */
-  postsPerPage?: number;
-  /** The name of the default collection used by BlogList when none is specified. */
-  defaultCollection?: string;
-  /** Date format string for rendering post dates (e.g., 'MMMM dd, yyyy'). */
-  dateFormat?: string;
-  /** Field to sort posts by. Defaults to 'date'. */
-  sortBy?: 'date' | 'title' | 'sidebarPosition';
-}
+/**
+ */
+/**
+ */
 interface BoltdocsSecurityConfig {
   headers?: Record<string, string>;
   enableCSP?: boolean;
@@ -486,49 +778,4 @@ declare function defineConfig(config: BoltdocsConfig): BoltdocsConfig;
  */
 declare function resolveConfig(docsDir: string, root?: string): Promise<BoltdocsConfig>;
 //#endregion
-//#region src/node/mdx/shiki-adapter.d.ts
-interface ParsedMeta {
-  title?: string;
-  lineNumbers?: boolean;
-  wordWrap?: boolean;
-  [key: string]: any;
-}
-/**
- * Parses a meta string into a structured ParsedMeta object.
- */
-declare function parseMetaString(metaStr: string): ParsedMeta;
-/**
- * Unified Shiki Adapter for Boltdocs.
- * Centralizes theme resolution, transformer configuration, and rendering logic.
- */
-declare class ShikiAdapter {
-  private config;
-  constructor(config?: BoltdocsConfig);
-  /**
-   * Resolves the code theme from Boltdocs configuration.
-   */
-  getTheme(): ShikiTheme | {
-    light: ShikiTheme;
-    dark: ShikiTheme;
-  };
-  /**
-   * Creates a Shiki highlighter instance with the configured themes.
-   */
-  getHighlighter(): Promise<_$shiki.HighlighterCore>;
-  /**
-   * Assembles Shiki options including transformers for a specific code block.
-   */
-  getOptions(lang: string, meta: string | ParsedMeta): CodeToHastOptions;
-  /**
-   * Renders code to HTML using the Boltdocs Shiki pipeline.
-   * Safely handles highlighter exceptions by falling back to escaped pre.
-   */
-  render(code: string, lang: string, meta: string | ParsedMeta): Promise<string>;
-}
-/**
- * Returns a cached ShikiAdapter instance.
- * Recreates only if the relevant codeTheme configuration values change deeply.
- */
-declare function getShikiAdapter(config?: BoltdocsConfig): ShikiAdapter;
-//#endregion
-export { resolveConfig as a, BoltdocsPlugin as c, PluginLifecycleHooks as d, PluginLogger as f, RouteMeta as h, parseMetaString as i, BoltdocsThemeConfig as l, PluginStore as m, ShikiAdapter as n, defineConfig as o, PluginMeta as p, getShikiAdapter as r, BoltdocsConfig as s, ParsedMeta as t, PluginContext as u };
+export { BoltdocsThemeConfig as a, PluginLogger as c, PluginTransformMiddleware as d, RouteMeta as f, BoltdocsPlugin as i, PluginMeta as l, defineConfig as n, PluginContext as o, ShikiTheme as p, BoltdocsConfig as r, PluginLifecycleHooks as s, resolveConfig as t, PluginStore as u };

package/dist/{csp-BX06rvdg.cjs → csp-CRp_3U7a.cjs}

@@ -3,4 +3,4 @@
  * Copyright (c) 2026 Jesus Alcala
  * Licensed under the MIT License.
  */
-var e=require(`./chunk-Ds5LZdWN.cjs`).t({getCSPHeader:()=>t});function t(e){let t=process.env.NODE_ENV===`development`,n={"default-src":[`'self'`],"script-src":[`'self'`,`'unsafe-inline'`],"style-src":[`'self'`,`'unsafe-inline'`],"img-src":[`'self'`,`data:`,`https:`],"font-src":[`'self'`],"connect-src":[`'self'`]};return t&&(n[`script-src`]=[`'self'`,`'unsafe-eval'`,`'unsafe-inline'`],n[`style-src`]=[`'self'`,`'unsafe-inline'`]),Object.entries(n).map(([e,t])=>`${e} ${t.join(` `)}`).join(`; `)}Object.defineProperty(exports,`n`,{enumerable:!0,get:function(){return t}}),Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return e}});
+var e=require(`./chunk-D1Md3oWO.cjs`).t({getCSPHeader:()=>t});function t(e){let t=process.env.NODE_ENV===`development`,n={"default-src":[`'self'`],"script-src":[`'self'`,`'unsafe-inline'`],"style-src":[`'self'`,`'unsafe-inline'`],"img-src":[`'self'`,`data:`,`https:`],"font-src":[`'self'`],"connect-src":[`'self'`]};return t&&(n[`script-src`]=[`'self'`,`'unsafe-eval'`,`'unsafe-inline'`],n[`style-src`]=[`'self'`,`'unsafe-inline'`]),Object.entries(n).map(([e,t])=>`${e} ${t.join(` `)}`).join(`; `)}Object.defineProperty(exports,`n`,{enumerable:!0,get:function(){return t}}),Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return e}});

package/dist/csp-oTC2ygvF.mjs

@@ -0,0 +1,6 @@
+/**
+ * Boltdocs - https://boltdocs.vercel.app
+ * Copyright (c) 2026 Jesus Alcala
+ * Licensed under the MIT License.
+ */
+import{t as e}from"./chunk-BFSpntXv.mjs";var t=e({getCSPHeader:()=>n});function n(e){let t=process.env.NODE_ENV===`development`,n={"default-src":[`'self'`],"script-src":[`'self'`,`'unsafe-inline'`],"style-src":[`'self'`,`'unsafe-inline'`],"img-src":[`'self'`,`data:`,`https:`],"font-src":[`'self'`],"connect-src":[`'self'`]};return t&&(n[`script-src`]=[`'self'`,`'unsafe-eval'`,`'unsafe-inline'`],n[`style-src`]=[`'self'`,`'unsafe-inline'`]),Object.entries(n).map(([e,t])=>`${e} ${t.join(` `)}`).join(`; `)}export{n,t};

package/dist/{docs-layout-DyLDBwS6.js → docs-layout-BdtZ9z6s.js}

@@ -3,7 +3,7 @@
  * Copyright (c) 2026 Jesus Alcala
  * Licensed under the MIT License.
  */
-import { A as ChevronRight, D as Check, S as normalizePath, _ as Link$1, b as useLocalizedTo, k as ChevronLeft, rt as useConfig, tt as icons_exports, y as cn } from "./icons-dev-CHZOwhQA.js";
+import { B as useConfig, R as icons_exports, d as Check, i as useLocalizedTo, m as ChevronRight, o as normalizePath, p as ChevronLeft, r as cn, t as Link$1 } from "./link-2PzgTnaP.js";
 import { Children, createContext, use, useContext, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { useLocation } from "react-router-dom";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -1142,15 +1142,8 @@ function SearchHighlight() {
 //#endregion
 //#region src/client/components/primitives/docs-layout.tsx
 /**
-* Root layout shell. Renders a full-height flex column.
-*
-* Usage:
-* ```tsx
-* <DocsLayout>
-*   <Navbar />
-*   <DocsLayout.Body>...</DocsLayout.Body>
-* </DocsLayout>
-* ```
+* Root layout shell. Mount children like:
+*   <DocsLayout><Navbar /><DocsLayout.Body>...</DocsLayout.Body></DocsLayout>
 */
 function DocsLayoutRoot({ children, className, style }) {
 	return /* @__PURE__ */ jsx("div", {
@@ -1159,9 +1152,6 @@ function DocsLayoutRoot({ children, className, style }) {
 		children
 	});
 }
-/**
-* Horizontal flex container for sidebar + content + toc.
-*/
 function Body({ children, className, style }) {
 	return /* @__PURE__ */ jsx("div", {
 		className: cn("mx-auto flex flex-1 w-full max-w-(--breakpoint-3xl) bg-main overflow-hidden", className),
@@ -1169,29 +1159,23 @@ function Body({ children, className, style }) {
 		children
 	});
 }
-/**
-* Main scrollable content area.
-*/
 function Content({ children, className, style }) {
 	return /* @__PURE__ */ jsx("main", {
-		className: cn("boltdocs-content flex-1 min-w-0 overflow-y-auto", "contain-layout", className),
+		className: cn("boltdocs-content flex-1 min-w-0 overflow-y-auto", className),
 		style,
 		children
 	});
 }
-/**
-* MDX Content wrapper with standard page padding and max-width logic.
-*/
 function ContentMdx({ children, className, style }) {
 	return /* @__PURE__ */ jsxs("div", {
-		className: cn("boltdocs-page mx-auto pt-4 pb-20 px-4 sm:px-8", className),
+		className: cn("boltdocs-page w-full pt-4 pb-20 px-4 sm:px-8", className),
 		style,
-		children: [/* @__PURE__ */ jsx(SearchHighlight, {}), children]
+		children: [/* @__PURE__ */ jsx(SearchHighlight, {}), /* @__PURE__ */ jsx("div", {
+			className: "mx-auto w-full max-w-3xl sm:max-w-4xl lg:max-w-5xl",
+			children
+		})]
 	});
 }
-/**
-* Content header area (breadcrumbs, title, description, etc).
-*/
 function Header({ children, className, style }) {
 	return /* @__PURE__ */ jsx("header", {
 		className: cn("mb-10", className),
@@ -1199,9 +1183,6 @@ function Header({ children, className, style }) {
 		children
 	});
 }
-/**
-* Footer area inside the content section (page nav).
-*/
 function Footer({ children, className, style }) {
 	return /* @__PURE__ */ jsx("div", {
 		className: cn("mt-20", className),