boltdocs 2.4.1 → 2.5.0

package/dist/node/index.d.mts

@@ -1,5 +1,97 @@
 import * as vite from 'vite';
 import { Plugin, InlineConfig } from 'vite';
+import { z } from 'zod';
+
+/**
+ * Permissions that a plugin can request to access specific Boltdocs capabilities.
+ */
+type PluginPermission = 'fs:read' | 'fs:write' | 'vite:config' | 'mdx:remark' | 'mdx:rehype' | 'components' | 'hooks:build' | 'hooks:dev';
+/**
+ * Shared context injected into every plugin lifecycle hook.
+ */
+interface PluginContext {
+    /** The full, resolved Boltdocs configuration (Readonly) */
+    readonly config: BoltdocsConfig;
+    /** A plugin-specific logger */
+    readonly logger: PluginLogger;
+    /** A shared store for dependency injection and state sharing between plugins */
+    readonly store: PluginStore;
+    /** Metadata about the current plugin */
+    readonly meta: PluginMeta;
+}
+/**
+ * Simple logger interface for plugins.
+ */
+interface PluginLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string | Error): void;
+    debug(message: string): void;
+}
+/**
+ * A shared key-value store that allows plugins to share state and configuration.
+ */
+interface PluginStore {
+    /** Get a value from the store. Keys are namespaced by plugin internally. */
+    get<T = unknown>(pluginName: string, key: string): T | undefined;
+    /** Set a value in the store. */
+    set(pluginName: string, key: string, value: unknown): void;
+    /** Check if a key exists in the store. */
+    has(pluginName: string, key: string): boolean;
+}
+/**
+ * Metadata for a plugin, used for identification and compatibility checks.
+ */
+interface PluginMeta {
+    /** Unique identifier for the plugin */
+    name: string;
+    /** Version of the plugin itself (semver) */
+    version?: string;
+    /** Minimum required version of Boltdocs (semver range) */
+    boltdocsVersion?: string;
+}
+/**
+ * Lifecycle hooks that a plugin can implement to hook into the build and dev processes.
+ */
+interface PluginLifecycleHooks {
+    /** Called before the build process starts */
+    beforeBuild?: (ctx: PluginContext) => Promise<void> | void;
+    /** Called after the build process finishes successfully */
+    afterBuild?: (ctx: PluginContext) => Promise<void> | void;
+    /** Called before the dev server starts */
+    beforeDev?: (ctx: PluginContext) => Promise<void> | void;
+    /** Called after the dev server is ready (configureServer) */
+    afterDev?: (ctx: PluginContext) => Promise<void> | void;
+    /** Called when the final Boltdocs config is resolved */
+    configResolved?: (ctx: PluginContext, config: BoltdocsConfig) => void;
+    /** Called when the build is closing */
+    buildEnd?: (ctx: PluginContext) => Promise<void> | void;
+}
+/**
+ * The extended, secure Boltdocs plugin interface.
+ */
+interface SecureBoltdocsPlugin {
+    /** A unique name for the plugin (e.g., 'boltdocs-plugin-mermaid') */
+    name: string;
+    /** Whether to run this plugin before or after default ones */
+    enforce?: 'pre' | 'post';
+    /** Version of the plugin (optional, but recommended for security) */
+    version?: string;
+    /** Minimum compatible Boltdocs version (optional, semver range) */
+    boltdocsVersion?: string;
+    /** List of permissions this plugin requires to operate */
+    permissions?: PluginPermission[];
+    /** Optional remark plugins to add to the MDX pipeline (requires 'mdx:remark' permission) */
+    remarkPlugins?: unknown[];
+    /** Optional rehype plugins to add to the MDX pipeline (requires 'mdx:rehype' permission) */
+    rehypePlugins?: unknown[];
+    /** Optional Vite plugins to inject into the build process (requires 'vite:config' permission) */
+    vitePlugins?: Plugin[];
+    /** Optional custom React components to register in MDX. Map of Name -> Module Path. (requires 'components' permission) */
+    components?: Record<string, string>;
+    /** Implementation of lifecycle hooks (requires 'hooks:build' or 'hooks:dev' permissions) */
+    hooks?: PluginLifecycleHooks;
+}
 
 /**
  * Represents a single social link in the configuration.
@@ -170,6 +262,12 @@ interface BoltdocsPlugin {
     name: string;
     /** Whether to run this plugin before or after default ones (optional) */
     enforce?: 'pre' | 'post';
+    /** Version of the plugin (optional) */
+    version?: string;
+    /** Minimum compatible Boltdocs version (optional, semver range) */
+    boltdocsVersion?: string;
+    /** List of permissions this plugin requires to operate */
+    permissions?: PluginPermission[];
     /** Optional remark plugins to add to the MDX pipeline */
     remarkPlugins?: unknown[];
     /** Optional rehype plugins to add to the MDX pipeline */
@@ -178,6 +276,8 @@ interface BoltdocsPlugin {
     vitePlugins?: Plugin[];
     /** Optional custom React components to register in MDX. Map of Name -> Module Path. */
     components?: Record<string, string>;
+    /** Implementation of lifecycle hooks */
+    hooks?: PluginLifecycleHooks;
 }
 /**
  * Configuration for external integrations (e.g., CodeSandbox).
@@ -191,6 +291,17 @@ interface BoltdocsIntegrationsConfig {
         config?: Record<string, unknown>;
     };
 }
+/**
+ * Configuration for security-related settings.
+ */
+interface BoltdocsSecurityConfig {
+    /** Map of standard security headers to override or supplement defaults */
+    headers?: Record<string, string>;
+    /** Whether to enable Content Security Policy (CSP) generation (default: false) */
+    enableCSP?: boolean;
+    /** Additional custom headers to inject into responses */
+    customHeaders?: Record<string, string>;
+}
 /**
  * The root configuration object for Boltdocs.
  */
@@ -213,6 +324,8 @@ interface BoltdocsConfig {
     integrations?: BoltdocsIntegrationsConfig;
     /** Configuration for the robots.txt file */
     robots?: BoltdocsRobotsConfig;
+    /** Security-related settings and headers */
+    security?: BoltdocsSecurityConfig;
     /** Low-level Vite configuration overrides */
     vite?: vite.InlineConfig;
 }
@@ -309,6 +422,155 @@ interface RouteMeta {
     _rawContent?: string;
 }
 
+/**
+ * Base class for all plugin-related errors in Boltdocs.
+ */
+declare class PluginError extends Error {
+    readonly pluginName: string;
+    constructor(pluginName: string, message: string);
+}
+/**
+ * Specifically for schema or structure validation failures.
+ */
+declare class PluginValidationError extends PluginError {
+    constructor(pluginName: string, message: string);
+}
+/**
+ * Specifically for version mismatch or compatibility issues.
+ */
+declare class PluginCompatibilityError extends PluginError {
+    constructor(pluginName: string, message: string);
+}
+/**
+ * Specifically for attempts to use capabilities without proper permissions.
+ */
+declare class PluginPermissionError extends PluginError {
+    constructor(pluginName: string, permission: string);
+}
+/**
+ * Specifically for errors that occur during the execution of a lifecycle hook.
+ */
+declare class PluginHookError extends PluginError {
+    readonly hookName: string;
+    constructor(pluginName: string, hookName: string, originalError: Error);
+}
+
+/**
+ * Implementation of the shared plugin store.
+ * Uses a namespaced approach to prevent key collisions between plugins.
+ */
+declare class BoltdocsPluginStore implements PluginStore {
+    private data;
+    /**
+     * Internal helper to create a namespaced key.
+     */
+    private getNamespaceKey;
+    /**
+     * Retrieves a value from the store. Returns a deep clone to prevent mutations (side-effects).
+     */
+    get<T = unknown>(pluginName: string, key: string): T | undefined;
+    /**
+     * Stores a value in the store. Key is automatically namespaced.
+     */
+    set(pluginName: string, key: string, value: unknown): void;
+    /**
+     * Checks for the existence of a key in the store.
+     */
+    has(pluginName: string, key: string): boolean;
+}
+
+/**
+ * Enhanced Zod schema for secure plugins.
+ */
+declare const SecurePluginSchema: z.ZodObject<{
+    name: z.ZodString;
+    enforce: z.ZodOptional<z.ZodEnum<{
+        pre: "pre";
+        post: "post";
+    }>>;
+    remarkPlugins: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    rehypePlugins: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    vitePlugins: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    components: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    version: z.ZodOptional<z.ZodString>;
+    boltdocsVersion: z.ZodOptional<z.ZodString>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hooks: z.ZodOptional<z.ZodObject<{
+        beforeBuild: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+        afterBuild: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+        beforeDev: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+        afterDev: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+        configResolved: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+        buildEnd: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Validates a list of plugins for correctness, security, and compatibility.
+ */
+declare function validatePlugins(plugins: any[], boltdocsVersion: string): SecureBoltdocsPlugin[];
+/**
+ * Helper to check if a specific permission is granted to a plugin.
+ */
+declare function hasPermission(plugin: SecureBoltdocsPlugin, permission: PluginPermission): boolean;
+
+/**
+ * The Sandbox provides a protective layer that ensures plugins only use
+ * the capabilities they have explicitly requested permissions for.
+ */
+declare class PluginSandbox {
+    /**
+     * Validates if a plugin has the required permission for a capability.
+     * Throws a PluginPermissionError if not granted.
+     */
+    static checkPermission(plugin: SecureBoltdocsPlugin, permission: PluginPermission): void;
+    /**
+     * Filters a plugin's capabilities based on its declared permissions.
+     * This is used when aggregating plugins (remark, rehype, vite, components).
+     */
+    static getSanitizedCapabilities(plugin: SecureBoltdocsPlugin): {
+        remarkPlugins: unknown[] | undefined;
+        rehypePlugins: unknown[] | undefined;
+        vitePlugins: vite.Plugin<any>[] | undefined;
+        components: Record<string, string> | undefined;
+    };
+    /**
+     * Wraps a hook execution with permission checks and error isolation.
+     */
+    static executeWithIsolation<T>(plugin: SecureBoltdocsPlugin, requiredPermission: PluginPermission, hookName: string, action: () => Promise<T> | T): Promise<T | undefined>;
+}
+
+/**
+ * Manages the lifecycle of all loaded plugins, ensuring hooks are executed
+ * in the correct order with proper error isolation and context.
+ */
+declare class PluginLifecycleManager {
+    private plugins;
+    private config;
+    private store;
+    constructor(plugins: SecureBoltdocsPlugin[], config: BoltdocsConfig);
+    /**
+     * Runs a specific hook for all plugins that implement it.
+     */
+    runHook(hookName: keyof PluginLifecycleHooks, ...args: any[]): Promise<void>;
+    /**
+     * Sorts plugins based on their 'enforce' property (pre -> normal -> post).
+     */
+    private getSortedPlugins;
+    /**
+     * Creates a specialized context for a plugin.
+     */
+    private createContext;
+    /**
+     * Creates a namespaced logger for a plugin.
+     */
+    private createLogger;
+}
+
+/**
+ * Utility to create a Boltdocs plugin with full type safety.
+ */
+declare function createPlugin(plugin: SecureBoltdocsPlugin): SecureBoltdocsPlugin;
+
 declare function boltdocs(options?: BoltdocsPluginOptions): Promise<Plugin[]>;
 /**
  * Generates the complete Vite configuration for a Boltdocs project.
@@ -316,4 +578,4 @@ declare function boltdocs(options?: BoltdocsPluginOptions): Promise<Plugin[]>;
  */
 declare function createViteConfig(root: string, mode?: 'development' | 'production'): Promise<InlineConfig>;
 
-export { type BoltdocsConfig, type BoltdocsPluginOptions, type BoltdocsThemeConfig, type RouteMeta, type SSGOptions, createViteConfig, boltdocs as default, defineConfig, generateStaticPages, resolveConfig };
+export { type BoltdocsConfig, type BoltdocsPlugin, type BoltdocsPluginOptions, BoltdocsPluginStore, type BoltdocsThemeConfig, PluginCompatibilityError, type PluginContext, PluginError, PluginHookError, type PluginLifecycleHooks, PluginLifecycleManager, type PluginLogger, type PluginMeta, type PluginPermission, PluginPermissionError, PluginSandbox, type PluginStore, PluginValidationError, type RouteMeta, type SSGOptions, type SecureBoltdocsPlugin, SecurePluginSchema, createPlugin, createViteConfig, boltdocs as default, defineConfig, generateStaticPages, hasPermission, resolveConfig, validatePlugins };

package/dist/node/index.d.ts

@@ -1,5 +1,97 @@
 import * as vite from 'vite';
 import { Plugin, InlineConfig } from 'vite';
+import { z } from 'zod';
+
+/**
+ * Permissions that a plugin can request to access specific Boltdocs capabilities.
+ */
+type PluginPermission = 'fs:read' | 'fs:write' | 'vite:config' | 'mdx:remark' | 'mdx:rehype' | 'components' | 'hooks:build' | 'hooks:dev';
+/**
+ * Shared context injected into every plugin lifecycle hook.
+ */
+interface PluginContext {
+    /** The full, resolved Boltdocs configuration (Readonly) */
+    readonly config: BoltdocsConfig;
+    /** A plugin-specific logger */
+    readonly logger: PluginLogger;
+    /** A shared store for dependency injection and state sharing between plugins */
+    readonly store: PluginStore;
+    /** Metadata about the current plugin */
+    readonly meta: PluginMeta;
+}
+/**
+ * Simple logger interface for plugins.
+ */
+interface PluginLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string | Error): void;
+    debug(message: string): void;
+}
+/**
+ * A shared key-value store that allows plugins to share state and configuration.
+ */
+interface PluginStore {
+    /** Get a value from the store. Keys are namespaced by plugin internally. */
+    get<T = unknown>(pluginName: string, key: string): T | undefined;
+    /** Set a value in the store. */
+    set(pluginName: string, key: string, value: unknown): void;
+    /** Check if a key exists in the store. */
+    has(pluginName: string, key: string): boolean;
+}
+/**
+ * Metadata for a plugin, used for identification and compatibility checks.
+ */
+interface PluginMeta {
+    /** Unique identifier for the plugin */
+    name: string;
+    /** Version of the plugin itself (semver) */
+    version?: string;
+    /** Minimum required version of Boltdocs (semver range) */
+    boltdocsVersion?: string;
+}
+/**
+ * Lifecycle hooks that a plugin can implement to hook into the build and dev processes.
+ */
+interface PluginLifecycleHooks {
+    /** Called before the build process starts */
+    beforeBuild?: (ctx: PluginContext) => Promise<void> | void;
+    /** Called after the build process finishes successfully */
+    afterBuild?: (ctx: PluginContext) => Promise<void> | void;
+    /** Called before the dev server starts */
+    beforeDev?: (ctx: PluginContext) => Promise<void> | void;
+    /** Called after the dev server is ready (configureServer) */
+    afterDev?: (ctx: PluginContext) => Promise<void> | void;
+    /** Called when the final Boltdocs config is resolved */
+    configResolved?: (ctx: PluginContext, config: BoltdocsConfig) => void;
+    /** Called when the build is closing */
+    buildEnd?: (ctx: PluginContext) => Promise<void> | void;
+}
+/**
+ * The extended, secure Boltdocs plugin interface.
+ */
+interface SecureBoltdocsPlugin {
+    /** A unique name for the plugin (e.g., 'boltdocs-plugin-mermaid') */
+    name: string;
+    /** Whether to run this plugin before or after default ones */
+    enforce?: 'pre' | 'post';
+    /** Version of the plugin (optional, but recommended for security) */
+    version?: string;
+    /** Minimum compatible Boltdocs version (optional, semver range) */
+    boltdocsVersion?: string;
+    /** List of permissions this plugin requires to operate */
+    permissions?: PluginPermission[];
+    /** Optional remark plugins to add to the MDX pipeline (requires 'mdx:remark' permission) */
+    remarkPlugins?: unknown[];
+    /** Optional rehype plugins to add to the MDX pipeline (requires 'mdx:rehype' permission) */
+    rehypePlugins?: unknown[];
+    /** Optional Vite plugins to inject into the build process (requires 'vite:config' permission) */
+    vitePlugins?: Plugin[];
+    /** Optional custom React components to register in MDX. Map of Name -> Module Path. (requires 'components' permission) */
+    components?: Record<string, string>;
+    /** Implementation of lifecycle hooks (requires 'hooks:build' or 'hooks:dev' permissions) */
+    hooks?: PluginLifecycleHooks;
+}
 
 /**
  * Represents a single social link in the configuration.
@@ -170,6 +262,12 @@ interface BoltdocsPlugin {
     name: string;
     /** Whether to run this plugin before or after default ones (optional) */
     enforce?: 'pre' | 'post';
+    /** Version of the plugin (optional) */
+    version?: string;
+    /** Minimum compatible Boltdocs version (optional, semver range) */
+    boltdocsVersion?: string;
+    /** List of permissions this plugin requires to operate */
+    permissions?: PluginPermission[];
     /** Optional remark plugins to add to the MDX pipeline */
     remarkPlugins?: unknown[];
     /** Optional rehype plugins to add to the MDX pipeline */
@@ -178,6 +276,8 @@ interface BoltdocsPlugin {
     vitePlugins?: Plugin[];
     /** Optional custom React components to register in MDX. Map of Name -> Module Path. */
     components?: Record<string, string>;
+    /** Implementation of lifecycle hooks */
+    hooks?: PluginLifecycleHooks;
 }
 /**
  * Configuration for external integrations (e.g., CodeSandbox).
@@ -191,6 +291,17 @@ interface BoltdocsIntegrationsConfig {
         config?: Record<string, unknown>;
     };
 }
+/**
+ * Configuration for security-related settings.
+ */
+interface BoltdocsSecurityConfig {
+    /** Map of standard security headers to override or supplement defaults */
+    headers?: Record<string, string>;
+    /** Whether to enable Content Security Policy (CSP) generation (default: false) */
+    enableCSP?: boolean;
+    /** Additional custom headers to inject into responses */
+    customHeaders?: Record<string, string>;
+}
 /**
  * The root configuration object for Boltdocs.
  */
@@ -213,6 +324,8 @@ interface BoltdocsConfig {
     integrations?: BoltdocsIntegrationsConfig;
     /** Configuration for the robots.txt file */
     robots?: BoltdocsRobotsConfig;
+    /** Security-related settings and headers */
+    security?: BoltdocsSecurityConfig;
     /** Low-level Vite configuration overrides */
     vite?: vite.InlineConfig;
 }
@@ -309,6 +422,155 @@ interface RouteMeta {
     _rawContent?: string;
 }
 
+/**
+ * Base class for all plugin-related errors in Boltdocs.
+ */
+declare class PluginError extends Error {
+    readonly pluginName: string;
+    constructor(pluginName: string, message: string);
+}
+/**
+ * Specifically for schema or structure validation failures.
+ */
+declare class PluginValidationError extends PluginError {
+    constructor(pluginName: string, message: string);
+}
+/**
+ * Specifically for version mismatch or compatibility issues.
+ */
+declare class PluginCompatibilityError extends PluginError {
+    constructor(pluginName: string, message: string);
+}
+/**
+ * Specifically for attempts to use capabilities without proper permissions.
+ */
+declare class PluginPermissionError extends PluginError {
+    constructor(pluginName: string, permission: string);
+}
+/**
+ * Specifically for errors that occur during the execution of a lifecycle hook.
+ */
+declare class PluginHookError extends PluginError {
+    readonly hookName: string;
+    constructor(pluginName: string, hookName: string, originalError: Error);
+}
+
+/**
+ * Implementation of the shared plugin store.
+ * Uses a namespaced approach to prevent key collisions between plugins.
+ */
+declare class BoltdocsPluginStore implements PluginStore {
+    private data;
+    /**
+     * Internal helper to create a namespaced key.
+     */
+    private getNamespaceKey;
+    /**
+     * Retrieves a value from the store. Returns a deep clone to prevent mutations (side-effects).
+     */
+    get<T = unknown>(pluginName: string, key: string): T | undefined;
+    /**
+     * Stores a value in the store. Key is automatically namespaced.
+     */
+    set(pluginName: string, key: string, value: unknown): void;
+    /**
+     * Checks for the existence of a key in the store.
+     */
+    has(pluginName: string, key: string): boolean;
+}
+
+/**
+ * Enhanced Zod schema for secure plugins.
+ */
+declare const SecurePluginSchema: z.ZodObject<{
+    name: z.ZodString;
+    enforce: z.ZodOptional<z.ZodEnum<{
+        pre: "pre";
+        post: "post";
+    }>>;
+    remarkPlugins: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    rehypePlugins: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    vitePlugins: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    components: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    version: z.ZodOptional<z.ZodString>;
+    boltdocsVersion: z.ZodOptional<z.ZodString>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hooks: z.ZodOptional<z.ZodObject<{
+        beforeBuild: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+        afterBuild: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+        beforeDev: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+        afterDev: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+        configResolved: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+        buildEnd: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Validates a list of plugins for correctness, security, and compatibility.
+ */
+declare function validatePlugins(plugins: any[], boltdocsVersion: string): SecureBoltdocsPlugin[];
+/**
+ * Helper to check if a specific permission is granted to a plugin.
+ */
+declare function hasPermission(plugin: SecureBoltdocsPlugin, permission: PluginPermission): boolean;
+
+/**
+ * The Sandbox provides a protective layer that ensures plugins only use
+ * the capabilities they have explicitly requested permissions for.
+ */
+declare class PluginSandbox {
+    /**
+     * Validates if a plugin has the required permission for a capability.
+     * Throws a PluginPermissionError if not granted.
+     */
+    static checkPermission(plugin: SecureBoltdocsPlugin, permission: PluginPermission): void;
+    /**
+     * Filters a plugin's capabilities based on its declared permissions.
+     * This is used when aggregating plugins (remark, rehype, vite, components).
+     */
+    static getSanitizedCapabilities(plugin: SecureBoltdocsPlugin): {
+        remarkPlugins: unknown[] | undefined;
+        rehypePlugins: unknown[] | undefined;
+        vitePlugins: vite.Plugin<any>[] | undefined;
+        components: Record<string, string> | undefined;
+    };
+    /**
+     * Wraps a hook execution with permission checks and error isolation.
+     */
+    static executeWithIsolation<T>(plugin: SecureBoltdocsPlugin, requiredPermission: PluginPermission, hookName: string, action: () => Promise<T> | T): Promise<T | undefined>;
+}
+
+/**
+ * Manages the lifecycle of all loaded plugins, ensuring hooks are executed
+ * in the correct order with proper error isolation and context.
+ */
+declare class PluginLifecycleManager {
+    private plugins;
+    private config;
+    private store;
+    constructor(plugins: SecureBoltdocsPlugin[], config: BoltdocsConfig);
+    /**
+     * Runs a specific hook for all plugins that implement it.
+     */
+    runHook(hookName: keyof PluginLifecycleHooks, ...args: any[]): Promise<void>;
+    /**
+     * Sorts plugins based on their 'enforce' property (pre -> normal -> post).
+     */
+    private getSortedPlugins;
+    /**
+     * Creates a specialized context for a plugin.
+     */
+    private createContext;
+    /**
+     * Creates a namespaced logger for a plugin.
+     */
+    private createLogger;
+}
+
+/**
+ * Utility to create a Boltdocs plugin with full type safety.
+ */
+declare function createPlugin(plugin: SecureBoltdocsPlugin): SecureBoltdocsPlugin;
+
 declare function boltdocs(options?: BoltdocsPluginOptions): Promise<Plugin[]>;
 /**
  * Generates the complete Vite configuration for a Boltdocs project.
@@ -316,4 +578,4 @@ declare function boltdocs(options?: BoltdocsPluginOptions): Promise<Plugin[]>;
  */
 declare function createViteConfig(root: string, mode?: 'development' | 'production'): Promise<InlineConfig>;
 
-export { type BoltdocsConfig, type BoltdocsPluginOptions, type BoltdocsThemeConfig, type RouteMeta, type SSGOptions, createViteConfig, boltdocs as default, defineConfig, generateStaticPages, resolveConfig };
+export { type BoltdocsConfig, type BoltdocsPlugin, type BoltdocsPluginOptions, BoltdocsPluginStore, type BoltdocsThemeConfig, PluginCompatibilityError, type PluginContext, PluginError, PluginHookError, type PluginLifecycleHooks, PluginLifecycleManager, type PluginLogger, type PluginMeta, type PluginPermission, PluginPermissionError, PluginSandbox, type PluginStore, PluginValidationError, type RouteMeta, type SSGOptions, type SecureBoltdocsPlugin, SecurePluginSchema, createPlugin, createViteConfig, boltdocs as default, defineConfig, generateStaticPages, hasPermission, resolveConfig, validatePlugins };