@kubb/core 5.0.0-beta.1 → 5.0.0-beta.11

package/dist/{types-CuNocrbJ.d.ts → createKubb-BSfMDBwR.d.ts}

@@ -98,7 +98,7 @@ type PossiblePromise<T> = Promise<T> | T;
 /**
  * Base URL for the Kubb Studio web app.
  */
-declare const DEFAULT_STUDIO_URL: "https://studio.kubb.dev";
+declare const DEFAULT_STUDIO_URL: "https://kubb.studio";
 /**
  * Numeric log-level thresholds used internally to compare verbosity.
  *
@@ -113,6 +113,116 @@ declare const logLevel: {
   readonly debug: 5;
 };
 //#endregion
+//#region src/createAdapter.d.ts
+/**
+ * Source data passed to an adapter's `parse` function.
+ * Mirrors the config input shape with paths resolved to absolute.
+ */
+type AdapterSource = {
+  type: 'path';
+  path: string;
+} | {
+  type: 'data';
+  data: string | unknown;
+} | {
+  type: 'paths';
+  paths: Array<string>;
+};
+/**
+ * Generic type parameters for an adapter definition.
+ *
+ * - `TName` — unique identifier (e.g. `'oas'`, `'asyncapi'`)
+ * - `TOptions` — user-facing options passed to the adapter factory
+ * - `TResolvedOptions` — options after defaults applied
+ * - `TDocument` — type of the parsed source document
+ */
+type AdapterFactoryOptions<TName extends string = string, TOptions extends object = object, TResolvedOptions extends object = TOptions, TDocument = unknown> = {
+  name: TName;
+  options: TOptions;
+  resolvedOptions: TResolvedOptions;
+  document: TDocument;
+};
+/**
+ * Adapter that converts input files or data into an `InputNode`.
+ *
+ * Adapters parse different schema formats (OpenAPI, AsyncAPI, Drizzle, etc.) into Kubb's
+ * universal intermediate representation that all plugins consume.
+ *
+ * @example
+ * ```ts
+ * import { adapterOas } from '@kubb/adapter-oas'
+ *
+ * export default defineConfig({
+ *   adapter: adapterOas(),
+ *   input: { path: './openapi.yaml' },
+ *   plugins: [pluginTs(), pluginZod()],
+ * })
+ * ```
+ */
+type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
+  /**
+   * Human-readable adapter identifier (e.g. `'oas'`, `'asyncapi'`).
+   */
+  name: TOptions['name'];
+  /**
+   * Resolved adapter options after defaults have been applied.
+   */
+  options: TOptions['resolvedOptions'];
+  /**
+   * Parsed source document after the first `parse()` call. `null` before parsing.
+   */
+  document: TOptions['document'] | null;
+  inputNode: InputNode | null;
+  /**
+   * Parse the source into a universal `InputNode`.
+   */
+  parse: (source: AdapterSource) => PossiblePromise<InputNode>;
+  /**
+   * Extract `ImportNode` entries for a schema tree.
+   * Returns an empty array before the first `parse()` call.
+   *
+   * The `resolve` callback receives the collision-corrected schema name and must
+   * return `{ name, path }` for the import, or `undefined` to skip it.
+   */
+  getImports: (node: SchemaNode, resolve: (schemaName: string) => {
+    name: string;
+    path: string;
+  }) => Array<ImportNode>;
+  /**
+   * Validate the document at the given path or URL.
+   */
+  validate: (input: string, options?: {
+    throwOnError?: boolean;
+  }) => Promise<void>;
+};
+type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>;
+/**
+ * Factory for implementing custom adapters that translate non-OpenAPI specs into Kubb's AST.
+ *
+ * Use this to support GraphQL schemas, gRPC definitions, AsyncAPI, or custom domain-specific languages.
+ * Built-in adapters include `@kubb/adapter-oas` for OpenAPI and Swagger documents.
+ *
+ * @note Adapters must parse their input format to Kubb's `InputNode` structure.
+ *
+ * @example
+ * ```ts
+ * export const myAdapter = createAdapter<MyAdapter>((options) => {
+ *   return {
+ *     name: 'my-adapter',
+ *     options,
+ *     async parse(source) {
+ *       // Transform source format to InputNode
+ *       return { ... }
+ *     },
+ *   }
+ * })
+ *
+ * // Instantiate:
+ * const adapter = myAdapter({ validate: true })
+ * ```
+ */
+declare function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryOptions>(build: AdapterBuilder<T>): (options?: T['options']) => Adapter<T>;
+//#endregion
 //#region src/createRenderer.d.ts
 /**
  * Minimal interface any Kubb renderer must satisfy.
@@ -235,1559 +345,1600 @@ type Storage = {
  */
 declare function createStorage<TOptions = Record<string, never>>(build: (options: TOptions) => Storage): (options?: TOptions) => Storage;
 //#endregion
-//#region src/defineGenerator.d.ts
+//#region src/devtools.d.ts
+type DevtoolsOptions = {
+  /**
+   * Open the AST inspector in Kubb Studio (`/ast`). Defaults to the main Studio page.
+   * @default false
+   */
+  ast?: boolean;
+};
+//#endregion
+//#region src/defineParser.d.ts
+type PrintOptions = {
+  extname?: FileNode['extname'];
+};
+type Parser<TMeta extends object = any> = {
+  name: string;
+  /**
+   * File extensions this parser handles.
+   * Use `undefined` to create a catch-all fallback parser.
+   *
+   * @example Handled extensions
+   * `['.ts', '.js']`
+   */
+  extNames: Array<FileNode['extname']> | undefined;
+  /**
+   * Convert a resolved file to a string.
+   */
+  parse(file: FileNode<TMeta>, options?: PrintOptions): Promise<string> | string;
+};
 /**
- * Declares a named generator unit that walks the AST and emits files.
- *
- * Each method (`schema`, `operation`, `operations`) is called for the matching node type.
- * Each method returns `TElement | Array<FileNode> | void`. JSX-based generators require a `renderer` factory.
- * Return `Array<FileNode>` directly or call `ctx.upsertFile()` manually and return `void` to bypass rendering.
+ * Defines a parser with type safety. Creates parsers that transform generated files to strings based on their extension.
  *
- * @note Generators are consumed by plugins and registered via `ctx.addGenerator()` in `kubb:plugin:setup`.
+ * @note Call the returned factory with optional options to instantiate the parser.
  *
  * @example
  * ```ts
- * import { defineGenerator } from '@kubb/core'
- * import { jsxRenderer } from '@kubb/renderer-jsx'
+ * import { defineParser } from '@kubb/core'
  *
- * export const typeGenerator = defineGenerator({
- *   name: 'typescript',
- *   renderer: jsxRenderer,
- *   schema(node, ctx) {
- *     const { adapter, resolver, root, options } = ctx
- *     return <File ...><Type node={node} resolver={resolver} /></File>
+ * export const jsonParser = defineParser({
+ *   name: 'json',
+ *   extNames: ['.json'],
+ *   parse(file) {
+ *     const { extractStringsFromNodes } = await import('@kubb/ast')
+ *     return file.sources.map((s) => extractStringsFromNodes(s.nodes ?? [])).join('\n')
  *   },
  * })
  * ```
  */
-type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown> = {
-  /**
-   * Used in diagnostic messages and debug output.
-   */
-  name: string;
-  /**
-   * Optional renderer factory that produces a {@link Renderer} for each render cycle.
-   *
-   * Generators that return renderer elements (e.g. JSX via `@kubb/renderer-jsx`) must set this
-   * to the matching renderer factory (e.g. `jsxRenderer` from `@kubb/renderer-jsx`).
-   *
-   * Generators that only return `Array<FileNode>` or `void` do not need to set this.
-   *
-   * Set `renderer: null` to explicitly opt out of rendering even when the parent plugin
-   * declares a `renderer` (overrides the plugin-level fallback).
-   *
-   * @example
-   * ```ts
-   * import { jsxRenderer } from '@kubb/renderer-jsx'
-   * export const myGenerator = defineGenerator<PluginTs>({
-   *   renderer: jsxRenderer,
-   *   schema(node, ctx) { return <File ...>...</File> },
-   * })
-   * ```
-   */
-  renderer?: RendererFactory<TElement> | null;
-  /**
-   * Called for each schema node in the AST walk.
-   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
-   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
-   */
-  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>;
-  /**
-   * Called for each operation node in the AST walk.
-   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
-   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
-   */
-  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>;
+declare function defineParser<TMeta extends object = any>(parser: Parser<TMeta>): Parser<TMeta>;
+//#endregion
+//#region src/FileProcessor.d.ts
+type ParseOptions = {
+  parsers?: Map<FileNode['extname'], Parser>;
+  extension?: Record<FileNode['extname'], FileNode['extname'] | ''>;
+};
+type RunOptions = ParseOptions & {
   /**
-   * Called once after all operations have been walked.
-   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
-   * plus `ctx.options` with the plugin-level options for the batch call.
+   * @default 'sequential'
    */
-  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>;
+  mode?: 'sequential' | 'parallel';
+};
+type FileProcessorEvents = {
+  start: [files: Array<FileNode>];
+  update: [params: {
+    file: FileNode;
+    source?: string;
+    processed: number;
+    total: number;
+    percentage: number;
+  }];
+  end: [files: Array<FileNode>];
 };
 /**
- * Defines a generator. Returns the object as-is with correct `this` typings.
- * `applyHookResult` handles renderer elements and `File[]` uniformly using
- * the generator's declared `renderer` factory.
- */
-declare function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(generator: Generator<TOptions, TElement>): Generator<TOptions, TElement>;
-//#endregion
-//#region src/definePlugin.d.ts
-/**
- * A plugin object produced by `definePlugin`.
- * Instead of flat lifecycle methods, it groups all handlers under a `hooks:` property
- * (matching Astro's integration naming convention).
+ * Converts a single file to a string using the registered parsers.
+ * Falls back to joining source values when no matching parser is found.
  *
- * @template TFactory - The plugin's `PluginFactoryOptions` type.
+ * @internal
  */
-type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
+declare class FileProcessor {
+  #private;
+  readonly events: AsyncEventEmitter<FileProcessorEvents>;
+  parse(file: FileNode, {
+    parsers,
+    extension
+  }?: ParseOptions): Promise<string>;
+  run(files: Array<FileNode>, {
+    parsers,
+    mode,
+    extension
+  }?: RunOptions): Promise<Array<FileNode>>;
+}
+//#endregion
+//#region src/defineLogger.d.ts
+type LoggerOptions = {
   /**
-   * Unique name for the plugin, following the same naming convention as `createPlugin`.
+   * Log level for output verbosity.
+   * @default 3
    */
+  logLevel: (typeof logLevel)[keyof typeof logLevel];
+};
+/**
+ * Shared context passed to plugins, parsers, and other internals.
+ */
+type LoggerContext = AsyncEventEmitter<KubbHooks>;
+type Logger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = {
   name: string;
-  /**
-   * Plugins that must be registered before this plugin executes.
-   * An error is thrown at startup when any listed dependency is missing.
-   */
-  dependencies?: Array<string>;
-  /**
-   * Controls the execution order of this plugin relative to others.
-   *
-   * - `'pre'`  — runs before all normal plugins.
-   * - `'post'` — runs after all normal plugins.
-   * - `undefined` (default) — runs in declaration order among normal plugins.
-   *
-   * Dependency constraints always take precedence over `enforce`.
-   */
-  enforce?: 'pre' | 'post';
-  /**
-   * The options passed by the user when calling the plugin factory.
-   */
-  options?: TFactory['options'];
-  /**
-   * Lifecycle event handlers for this plugin.
-   * Any event from the global `KubbHooks` map can be subscribed to here.
-   */
-  hooks: { [K in Exclude<keyof KubbHooks, 'kubb:plugin:setup'>]?: (...args: KubbHooks[K]) => void | Promise<void> } & {
-    'kubb:plugin:setup'?(ctx: KubbPluginSetupContext<TFactory>): void | Promise<void>;
-  };
+  install: (context: LoggerContext, options?: TOptions) => TInstallReturn | Promise<TInstallReturn>;
 };
+type UserLogger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = Logger<TOptions, TInstallReturn>;
 /**
- * Wraps a factory function and returns a typed `Plugin` with lifecycle handlers grouped under `hooks`.
- *
- * Handlers live in a single `hooks` object (inspired by Astro integrations).
- * All lifecycle events from `KubbHooks` are available for subscription.
+ * Wraps a logger definition into a typed {@link Logger}.
  *
- * @note For real plugins, use a `PluginFactoryOptions` type parameter to get type-safe context in `kubb:plugin:setup`.
- * Plugin names should follow the convention `plugin-<feature>` (e.g., `plugin-react-query`, `plugin-zod`).
+ * The optional second type parameter `TInstallReturn` allows loggers to return
+ * a value from `install` — for example, a sink factory that the caller can
+ * forward to hook execution.
  *
- * @example
+ * @example Basic logger
  * ```ts
- * import { definePlugin } from '@kubb/core'
- *
- * export const pluginTs = definePlugin((options: { prefix?: string } = {}) => ({
- *   name: 'plugin-ts',
- *   hooks: {
- *     'kubb:plugin:setup'(ctx) {
- *       ctx.setResolver(resolverTs)
- *     },
+ * export const myLogger = defineLogger({
+ *   name: 'my-logger',
+ *   install(context, options) {
+ *     context.on('kubb:info', (message) => console.log('ℹ', message))
+ *     context.on('kubb:error', (error) => console.error('✗', error.message))
  *   },
- * }))
+ * })
  * ```
- */
-declare function definePlugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>(factory: (options: TFactory['options']) => Plugin<TFactory>): (options?: TFactory['options']) => Plugin<TFactory>;
-//#endregion
-//#region src/FileManager.d.ts
-/**
- * In-memory file store for generated files.
  *
- * Files with the same `path` are merged — sources, imports, and exports are concatenated.
- * The `files` getter returns all stored files sorted by path length (shortest first).
- *
- * @example
+ * @example Logger that returns a hook sink factory
  * ```ts
- * import { FileManager } from '@kubb/core'
- *
- * const manager = new FileManager()
- * manager.upsert(myFile)
- * console.log(manager.files) // all stored files
+ * export const myLogger = defineLogger<LoggerOptions, HookSinkFactory>({
+ *   name: 'my-logger',
+ *   install(context, options) {
+ *     // … register event handlers …
+ *     return (commandWithArgs) => ({ onStdout: console.log })
+ *   },
+ * })
  * ```
  */
-declare class FileManager {
-  #private;
-  /**
-   * Adds one or more files. Incoming files with the same path are merged
-   * (sources/imports/exports concatenated), but existing cache entries are
-   * replaced — use {@link upsert} when you want to merge into the cache too.
-   */
-  add(...files: Array<FileNode>): Array<FileNode>;
-  /**
-   * Adds or merges one or more files.
-   * If a file with the same path already exists in the cache, its
-   * sources/imports/exports are merged into the incoming file.
-   */
-  upsert(...files: Array<FileNode>): Array<FileNode>;
-  getByPath(path: string): FileNode | null;
-  deleteByPath(path: string): void;
-  clear(): void;
-  /**
-   * All stored files, sorted by path length (shorter paths first).
-   */
-  get files(): Array<FileNode>;
-}
-//#endregion
-//#region src/PluginDriver.d.ts
-type Options = {
-  hooks: AsyncEventEmitter<KubbHooks>;
-};
-declare class PluginDriver {
-  #private;
-  readonly config: Config;
-  readonly options: Options;
-  /**
-   * Returns `'single'` when `fileOrFolder` has a file extension, `'split'` otherwise.
-   *
-   * @example
-   * ```ts
-   * PluginDriver.getMode('src/gen/types.ts')  // 'single'
-   * PluginDriver.getMode('src/gen/types')     // 'split'
-   * ```
-   */
-  static getMode(fileOrFolder: string | undefined | null): 'single' | 'split';
-  /**
-   * The universal `@kubb/ast` `InputNode` produced by the adapter, set by
-   * the build pipeline after the adapter's `parse()` resolves.
-   */
-  inputNode: InputNode | undefined;
-  adapter: Adapter | undefined;
-  /**
-   * Central file store for all generated files.
-   * Plugins should use `this.addFile()` / `this.upsertFile()` (via their context) to
-   * add files; this property gives direct read/write access when needed.
-   */
-  readonly fileManager: FileManager;
-  readonly plugins: Map<string, NormalizedPlugin>;
-  constructor(config: Config, options: Options);
-  get hooks(): AsyncEventEmitter<KubbHooks>;
-  /**
-   * Registers a hook-style plugin's lifecycle handlers on the shared `AsyncEventEmitter`.
-   *
-   * For `kubb:plugin:setup`, the registered listener wraps the globally emitted context with a
-   * plugin-specific one so that `addGenerator`, `setResolver`, `setTransformer`, and
-   * `setRenderer` all target the correct `normalizedPlugin` entry in the plugins map.
-   *
-   * All other hooks are iterated and registered directly as pass-through listeners.
-   * Any event key present in the global `KubbHooks` interface can be subscribed to.
-   *
-   * External tooling can subscribe to any of these events via `hooks.on(...)` to observe
-   * the plugin lifecycle without modifying plugin behavior.
-   *
-   * @internal
-   */
-  registerPluginHooks(hookPlugin: Plugin, normalizedPlugin: NormalizedPlugin): void;
-  /**
-   * Emits the `kubb:plugin:setup` event so that all registered hook-style plugin listeners
-   * can configure generators, resolvers, transformers and renderers before `buildStart` runs.
-   *
-   * Call this once from `safeBuild` before the plugin execution loop begins.
-   */
-  emitSetupHooks(): Promise<void>;
-  /**
-   * Registers a generator for the given plugin on the shared event emitter.
-   *
-   * The generator's `schema`, `operation`, and `operations` methods are registered as
-   * listeners on `kubb:generate:schema`, `kubb:generate:operation`, and `kubb:generate:operations`
-   * respectively. Each listener is scoped to the owning plugin via a `ctx.plugin.name` check
-   * so that generators from different plugins do not cross-fire.
-   *
-   * The renderer resolution chain is: `generator.renderer → plugin.renderer → config.renderer`.
-   * Set `generator.renderer = null` to explicitly opt out of rendering even when the plugin
-   * declares a renderer.
-   *
-   * Call this method inside `addGenerator()` (in `kubb:plugin:setup`) to wire up a generator.
-   */
-  registerGenerator(pluginName: string, gen: Generator): void;
-  /**
-   * Returns `true` when at least one generator was registered for the given plugin
-   * via `addGenerator()` in `kubb:plugin:setup` (event-based path).
-   *
-   * Used by the build loop to decide whether to walk the AST and emit generator events
-   * for a plugin that has no static `plugin.generators`.
-   */
-  hasRegisteredGenerators(pluginName: string): boolean;
-  /**
-   * Unregisters all plugin lifecycle listeners from the shared event emitter.
-   * Called at the end of a build to prevent listener leaks across repeated builds.
-   *
-   * @internal
-   */
-  dispose(): void;
-  /**
-   * Merges `partial` with the plugin's default resolver and stores the result.
-   * Also mirrors it onto `plugin.resolver` so callers using `getPlugin(name).resolver`
-   * get the up-to-date resolver without going through `getResolver()`.
-   */
-  setPluginResolver(pluginName: string, partial: Partial<Resolver>): void;
-  /**
-   * Returns the resolver for the given plugin.
-   *
-   * Resolution order: dynamic resolver set via `setPluginResolver` → static resolver on the
-   * plugin → lazily created default resolver (identity name, no path transforms).
-   */
-  getResolver<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Kubb.PluginRegistry[TName]['resolver'];
-  getResolver<TResolver extends Resolver = Resolver>(pluginName: string): TResolver;
-  getContext<TOptions extends PluginFactoryOptions>(plugin: NormalizedPlugin<TOptions>): GeneratorContext<TOptions> & Record<string, unknown>;
-  getPlugin<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined;
-  getPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(pluginName: string): Plugin<TOptions> | undefined;
-  /**
-   * Like `getPlugin` but throws a descriptive error when the plugin is not found.
-   */
-  requirePlugin<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Plugin<Kubb.PluginRegistry[TName]>;
-  requirePlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(pluginName: string): Plugin<TOptions>;
-}
+declare function defineLogger<Options extends LoggerOptions = LoggerOptions, TInstallReturn = void>(logger: UserLogger<Options, TInstallReturn>): Logger<Options, TInstallReturn>;
 //#endregion
-//#region src/createKubb.d.ts
+//#region src/defineMiddleware.d.ts
 /**
- * Full output produced by a successful or failed build.
+ * A middleware instance produced by calling a factory created with `defineMiddleware`.
+ * It declares event handlers under a `hooks` object which are registered on the
+ * shared emitter after all plugin hooks, so middleware handlers for any event
+ * always fire last.
  */
-type BuildOutput = {
-  /**
-   * Plugins that threw during installation, paired with the caught error.
-   */
-  failedPlugins: Set<{
-    plugin: Plugin;
-    error: Error;
-  }>;
-  files: Array<FileNode>;
-  driver: PluginDriver;
+type Middleware = {
   /**
-   * Elapsed time in milliseconds for each plugin, keyed by plugin name.
+   * Unique identifier for this middleware.
    */
-  pluginTimings: Map<string, number>;
-  error?: Error;
+  name: string;
   /**
-   * Raw generated source, keyed by absolute file path.
+   * Lifecycle event handlers for this middleware.
+   * Any event from the global `KubbHooks` map can be subscribed to here.
+   * Handlers are registered after all plugin handlers, so they always fire last.
    */
-  sources: Map<string, string>;
-};
-type CreateKubbOptions = {
-  hooks?: AsyncEventEmitter<KubbHooks>;
+  hooks: { [K in keyof KubbHooks]?: (...args: KubbHooks[K]) => void | Promise<void> };
 };
 /**
- * Creates a Kubb instance bound to a single config entry.
+ * Creates a middleware factory using the hook-style `hooks` API.
  *
- * Accepts a user-facing config shape and resolves it to a full {@link Config} during
- * `setup()`. The instance then holds shared state (`hooks`, `sources`, `driver`, `config`)
- * across the `setup → build` lifecycle. Attach event listeners to `kubb.hooks` before
- * calling `setup()` or `build()`.
+ * Middleware handlers fire after all plugin handlers for any given event, making them ideal for post-processing, logging, and auditing.
+ * Per-build state (such as accumulators) belongs inside the factory closure so each `createKubb` invocation gets its own isolated instance.
+ *
+ * @note The factory can accept typed options. See examples for using options and per-build state patterns.
  *
  * @example
  * ```ts
- * const kubb = createKubb(userConfig)
+ * import { defineMiddleware } from '@kubb/core'
  *
- * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
- *   console.log(`${plugin.name} completed in ${duration}ms`)
- * })
+ * // Stateless middleware
+ * export const logMiddleware = defineMiddleware(() => ({
+ *   name: 'log-middleware',
+ *   hooks: {
+ *     'kubb:build:end'({ files }) {
+ *       console.log(`Build complete with ${files.length} files`)
+ *     },
+ *   },
+ * }))
  *
- * const { files, failedPlugins } = await kubb.safeBuild()
+ * // Middleware with options and per-build state
+ * export const prefixMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
+ *   const seen = new Set<string>()
+ *   return {
+ *     name: 'prefix-middleware',
+ *     hooks: {
+ *       'kubb:plugin:end'({ plugin }) {
+ *         seen.add(`${options.prefix}${plugin.name}`)
+ *       },
+ *     },
+ *   }
+ * })
  * ```
  */
-declare function createKubb(userConfig: UserConfig, options?: CreateKubbOptions): Kubb$1;
+declare function defineMiddleware<TOptions extends object = object>(factory: (options: TOptions) => Middleware): (options?: TOptions) => Middleware;
 //#endregion
-//#region src/Kubb.d.ts
+//#region src/defineResolver.d.ts
 /**
- * Kubb code generation instance returned by {@link createKubb}.
- *
- * Use this when orchestrating multiple builds, inspecting plugin timings, or integrating Kubb into a larger toolchain.
- * For a single one-off build, chain directly: `await createKubb(config).build()`.
+ * Type/string pattern filter for include/exclude/override matching.
  */
-type Kubb$1 = {
-  /**
-   * Shared event emitter for lifecycle and status events. Attach listeners before calling `setup()` or `build()`.
-   */
-  readonly hooks: AsyncEventEmitter<KubbHooks>;
-  /**
-   * Generated source code keyed by absolute file path. Available after `build()` or `safeBuild()` completes.
-   */
-  readonly sources: Map<string, string>;
-  /**
-   * Plugin driver managing all plugins. Available after `setup()` completes.
-   */
-  readonly driver: PluginDriver | undefined;
-  /**
-   * Resolved configuration with defaults applied. Available after `setup()` completes.
-   */
-  readonly config: Config | undefined;
-  /**
-   * Resolves config and initializes the driver. `build()` calls this automatically.
-   */
-  setup(): Promise<void>;
-  /**
-   * Runs the full pipeline and throws on any plugin error. Automatically calls `setup()` if needed.
-   */
-  build(): Promise<BuildOutput>;
-  /**
-   * Runs the full pipeline and captures errors in `BuildOutput` instead of throwing. Automatically calls `setup()` if needed.
-   */
-  safeBuild(): Promise<BuildOutput>;
+type PatternFilter = {
+  type: string;
+  pattern: string | RegExp;
 };
 /**
- * Lifecycle events emitted during Kubb code generation.
- * Use these for logging, progress tracking, and custom integrations.
- *
- * @example
- * ```typescript
- * import type { AsyncEventEmitter } from '@internals/utils'
- * import type { KubbHooks } from '@kubb/core'
+ * Pattern filter with partial option overrides applied when the pattern matches.
+ */
+type PatternOverride<TOptions> = PatternFilter & {
+  options: Omit<Partial<TOptions>, 'override'>;
+};
+/**
+ * Context for resolving filtered options for a given operation or schema node.
  *
- * const hooks: AsyncEventEmitter<KubbHooks> = new AsyncEventEmitter()
+ * @internal
+ */
+type ResolveOptionsContext<TOptions> = {
+  options: TOptions;
+  exclude?: Array<PatternFilter>;
+  include?: Array<PatternFilter>;
+  override?: Array<PatternOverride<TOptions>>;
+};
+/**
+ * Base constraint for all plugin resolver objects.
  *
- * hooks.on('kubb:lifecycle:start', () => {
- *   console.log('Starting Kubb generation')
- * })
+ * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
+ * are injected automatically by `defineResolver` — extend this type to add custom resolution methods.
  *
- * hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
- *   console.log(`Plugin ${plugin.name} completed in ${duration}ms`)
- * })
+ * @example
+ * ```ts
+ * type MyResolver = Resolver & {
+ *   resolveName(node: SchemaNode): string
+ *   resolveTypedName(node: SchemaNode): string
+ * }
  * ```
  */
-interface KubbHooks {
+type Resolver = {
+  name: string;
+  pluginName: string;
+  default(name: string, type?: 'file' | 'function' | 'type' | 'const'): string;
+  resolveOptions<TOptions>(node: Node, context: ResolveOptionsContext<TOptions>): TOptions | null;
+  resolvePath(params: ResolverPathParams, context: ResolverContext): string;
+  resolveFile(params: ResolverFileParams, context: ResolverContext): FileNode;
+  resolveBanner(node: InputNode | null, context: ResolveBannerContext): string | undefined;
+  resolveFooter(node: InputNode | null, context: ResolveBannerContext): string | undefined;
+};
+/**
+ * File-specific parameters for `Resolver.resolvePath`.
+ *
+ * Pass alongside a `ResolverContext` to identify which file to resolve.
+ * Provide `tag` for tag-based grouping or `path` for path-based grouping.
+ *
+ * @example
+ * ```ts
+ * resolver.resolvePath(
+ *   { baseName: 'petTypes.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → '/src/types/petsController/petTypes.ts'
+ * ```
+ */
+type ResolverPathParams = {
+  baseName: FileNode['baseName'];
+  pathMode?: 'single' | 'split';
   /**
-   * Fires at the start of the Kubb lifecycle, before code generation begins.
+   * Tag value used when `group.type === 'tag'`.
    */
-  'kubb:lifecycle:start': [ctx: KubbLifecycleStartContext];
+  tag?: string;
   /**
-   * Fires at the end of the Kubb lifecycle, after all code generation completes.
+   * Path value used when `group.type === 'path'`.
    */
-  'kubb:lifecycle:end': [];
+  path?: string;
+};
+/**
+ * Shared context passed as the second argument to `Resolver.resolvePath` and `Resolver.resolveFile`.
+ *
+ * Describes where on disk output is rooted, which output config is active, and the optional
+ * grouping strategy that controls subdirectory layout.
+ *
+ * @example
+ * ```ts
+ * const context: ResolverContext = {
+ *   root: config.root,
+ *   output,
+ *   group,
+ * }
+ * ```
+ */
+type ResolverContext = {
+  root: string;
+  output: Output;
+  group?: Group;
   /**
-   * Fires when configuration loading starts.
+   * Plugin name used to populate `meta.pluginName` on the resolved file.
    */
-  'kubb:config:start': [];
+  pluginName?: string;
+};
+/**
+ * File-specific parameters for `Resolver.resolveFile`.
+ *
+ * Pass alongside a `ResolverContext` to fully describe the file to resolve.
+ * `tag` and `path` are used only when a matching `group` is present in the context.
+ *
+ * @example
+ * ```ts
+ * resolver.resolveFile(
+ *   { name: 'listPets', extname: '.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
+ * ```
+ */
+type ResolverFileParams = {
+  name: string;
+  extname: FileNode['extname'];
   /**
-   * Fires when configuration loading completes.
+   * Tag value used when `group.type === 'tag'`.
    */
-  'kubb:config:end': [ctx: KubbConfigEndContext];
+  tag?: string;
   /**
-   * Fires when code generation starts.
+   * Path value used when `group.type === 'path'`.
    */
-  'kubb:generation:start': [ctx: KubbGenerationStartContext];
+  path?: string;
+};
+/**
+ * Context passed to `Resolver.resolveBanner` and `Resolver.resolveFooter`.
+ *
+ * `output` is optional — not every plugin configures a banner/footer.
+ * `config` carries the global Kubb config, used to derive the default Kubb banner.
+ *
+ * @example
+ * ```ts
+ * resolver.resolveBanner(inputNode, { output: { banner: '// generated' }, config })
+ * // → '// generated'
+ * ```
+ */
+type ResolveBannerContext = {
+  output?: Pick<Output, 'banner' | 'footer'>;
+  config: Config;
+};
+/**
+ * Builder type for the plugin-specific resolver fields.
+ *
+ * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
+ * are optional — built-in fallbacks are injected when omitted.
+ *
+ * Methods in the returned object can call sibling resolver methods via `this`.
+ */
+type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<T['resolver'], 'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter' | 'name' | 'pluginName'> & Partial<Pick<T['resolver'], 'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter'>> & {
+  name: string;
+  pluginName: T['name'];
+} & ThisType<T['resolver']>;
+/**
+ * Default option resolver — applies include/exclude filters and merges matching override options.
+ *
+ * Returns `null` when the node is filtered out by an `exclude` rule or not matched by any `include` rule.
+ *
+ * @example Include/exclude filtering
+ * ```ts
+ * const options = defaultResolveOptions(operationNode, {
+ *   options: { output: 'types' },
+ *   exclude: [{ type: 'tag', pattern: 'internal' }],
+ * })
+ * // → null when node has tag 'internal'
+ * ```
+ *
+ * @example Override merging
+ * ```ts
+ * const options = defaultResolveOptions(operationNode, {
+ *   options: { enumType: 'asConst' },
+ *   override: [{ type: 'operationId', pattern: 'listPets', options: { enumType: 'enum' } }],
+ * })
+ * // → { enumType: 'enum' } when operationId matches
+ * ```
+ */
+/**
+ * Defines a resolver for a plugin, injecting built-in defaults for name casing,
+ * include/exclude/override filtering, path resolution, and file construction.
+ *
+ * All four defaults can be overridden by providing them in the builder function:
+ * - `default` — name casing strategy (camelCase / PascalCase)
+ * - `resolveOptions` — include/exclude/override filtering
+ * - `resolvePath` — output path computation
+ * - `resolveFile` — full `FileNode` construction
+ *
+ * Methods in the returned object can call sibling resolver methods via `this`.
+ *
+ * @example Basic resolver with naming helpers
+ * ```ts
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'default',
+ *   resolveName(node) {
+ *     return this.default(node.name, 'function')
+ *   },
+ *   resolveTypedName(node) {
+ *     return this.default(node.name, 'type')
+ *   },
+ * }))
+ * ```
+ *
+ * @example Override resolvePath for a custom output structure
+ * ```ts
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'custom',
+ *   resolvePath({ baseName }, { root, output }) {
+ *     return path.resolve(root, output.path, 'generated', baseName)
+ *   },
+ * }))
+ * ```
+ *
+ * @example Use this.default inside a helper
+ * ```ts
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'default',
+ *   resolveParamName(node, param) {
+ *     return this.default(`${node.operationId} ${param.in} ${param.name}`, 'type')
+ *   },
+ * }))
+ * ```
+ */
+declare function defineResolver<T extends PluginFactoryOptions>(build: ResolverBuilder<T>): T['resolver'];
+//#endregion
+//#region src/definePlugin.d.ts
+/**
+ * Safely extracts a type from a registry, returning `{}` if the key doesn't exist.
+ * Enables optional interface augmentation for `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry`
+ * without requiring changes to core.
+ *
+ * @internal
+ */
+type ExtractRegistryKey$1<T, K extends PropertyKey> = K extends keyof T ? T[K] : {};
+/**
+ * Output configuration for generated files.
+ */
+type Output<_TOptions = unknown> = {
   /**
-   * Fires when code generation completes.
+   * Output folder or file path for generated code.
    */
-  'kubb:generation:end': [ctx: KubbGenerationEndContext];
+  path: string;
   /**
-   * Fires with a generation summary including summary lines, title, and success status.
+   * Text or function prepended to every generated file.
+   * When a function, receives the current `InputNode` and returns a string.
    */
-  'kubb:generation:summary': [ctx: KubbGenerationSummaryContext];
+  banner?: string | ((node?: InputNode) => string);
   /**
-   * Fires when code formatting starts (e.g., Biome or Prettier).
+   * Text or function appended to every generated file.
+   * When a function, receives the current `InputNode` and returns a string.
    */
-  'kubb:format:start': [];
+  footer?: string | ((node?: InputNode) => string);
   /**
-   * Fires when code formatting completes.
+   * Whether to override existing external files if they already exist.
+   * @default false
    */
-  'kubb:format:end': [];
+  override?: boolean;
+} & ExtractRegistryKey$1<Kubb.PluginOptionsRegistry, 'output'>;
+type Group = {
   /**
-   * Fires when linting starts.
+   * How to group files into subdirectories.
+   * - `'tag'` — group by OpenAPI tags
+   * - `'path'` — group by OpenAPI paths
    */
-  'kubb:lint:start': [];
+  type: 'tag' | 'path';
   /**
-   * Fires when linting completes.
+   * Function that returns the subdirectory name for a group value.
+   * Defaults to `${camelCase(group)}Controller` for tags, first path segment for paths.
    */
-  'kubb:lint:end': [];
+  name?: (context: {
+    group: string;
+  }) => string;
+};
+type ByTag = {
   /**
-   * Fires when plugin hooks execution starts.
+   * Filter by OpenAPI `tags` field. Matches one or more tags assigned to operations.
    */
-  'kubb:hooks:start': [];
+  type: 'tag';
   /**
-   * Fires when plugin hooks execution completes.
+   * Tag name to match (case-sensitive). Can be a literal string or regex pattern.
    */
-  'kubb:hooks:end': [];
+  pattern: string | RegExp;
+};
+type ByOperationId = {
   /**
-   * Fires when a single hook executes (e.g., format or lint). The callback is invoked when the command finishes.
+   * Filter by OpenAPI `operationId` field. Each operation (GET, POST, etc.) has a unique identifier.
    */
-  'kubb:hook:start': [ctx: KubbHookStartContext];
+  type: 'operationId';
   /**
-   * Fires when a single hook execution completes.
+   * Operation ID to match (case-sensitive). Can be a literal string or regex pattern.
    */
-  'kubb:hook:end': [ctx: KubbHookEndContext];
+  pattern: string | RegExp;
+};
+type ByPath = {
   /**
-   * Fires when a new Kubb version is available.
+   * Filter by OpenAPI `path` (URL endpoint). Useful to group or filter by service segments like `/pets`, `/users`, etc.
    */
-  'kubb:version:new': [ctx: KubbVersionNewContext];
+  type: 'path';
   /**
-   * Informational message event.
+   * URL path to match (case-sensitive). Can be a literal string or regex pattern. Matches against the full path.
    */
-  'kubb:info': [ctx: KubbInfoContext];
+  pattern: string | RegExp;
+};
+type ByMethod = {
   /**
-   * Error event, fired when an error occurs during generation.
+   * Filter by HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'head'`, `'options'`.
    */
-  'kubb:error': [ctx: KubbErrorContext];
+  type: 'method';
   /**
-   * Success message event.
+   * HTTP method to match (case-insensitive when using string, or regex for dynamic matching).
    */
-  'kubb:success': [ctx: KubbSuccessContext];
+  pattern: HttpMethod | RegExp;
+};
+type BySchemaName = {
   /**
-   * Warning message event.
+   * Filter by schema component name (TypeScript or JSON schema). Matches schemas in `#/components/schemas`.
    */
-  'kubb:warn': [ctx: KubbWarnContext];
+  type: 'schemaName';
   /**
-   * Debug event for detailed logging with timestamp and optional filename.
+   * Schema name to match (case-sensitive). Can be a literal string or regex pattern.
    */
-  'kubb:debug': [ctx: KubbDebugContext];
+  pattern: string | RegExp;
+};
+type ByContentType = {
   /**
-   * Fires when file processing starts with the list of files to process.
+   * Filter by response or request content type: `'application/json'`, `'application/xml'`, etc.
    */
-  'kubb:files:processing:start': [ctx: KubbFilesProcessingStartContext];
+  type: 'contentType';
   /**
-   * Fires for each file with progress updates: processed count, total, percentage, and file details.
-   */
-  'kubb:file:processing:update': [ctx: KubbFileProcessingUpdateContext];
-  /**
-   * Fires when file processing completes with the list of processed files.
+   * Content type to match (case-sensitive). Can be a literal string or regex pattern.
    */
-  'kubb:files:processing:end': [ctx: KubbFilesProcessingEndContext];
+  pattern: string | RegExp;
+};
+/**
+ * A pattern filter that prevents matching nodes from being generated.
+ *
+ * Use to skip code generation for specific operations or schemas. For example, exclude deprecated endpoints
+ * or internal-only schemas. Can filter by tag, operationId, path, HTTP method, content type, or schema name.
+ *
+ * @example
+ * ```ts
+ * exclude: [
+ *   { type: 'tag', pattern: 'internal' },          // skip "internal" tag
+ *   { type: 'path', pattern: /^\/admin/ },          // skip all /admin endpoints
+ *   { type: 'operationId', pattern: 'deprecated_*' }  // skip operationIds matching pattern
+ * ]
+ * ```
+ */
+type Exclude = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
+/**
+ * A pattern filter that restricts generation to only matching nodes.
+ *
+ * Use to generate code for a subset of operations or schemas. For example, only generate for a specific service
+ * tag or only for "production" endpoints. Can filter by tag, operationId, path, HTTP method, content type, or schema name.
+ *
+ * @example
+ * ```ts
+ * include: [
+ *   { type: 'tag', pattern: 'public' },        // generate only "public" tag
+ *   { type: 'path', pattern: /^\/api\/v1/ },   // generate only v1 endpoints
+ * ]
+ * ```
+ */
+type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
+/**
+ * A pattern filter paired with partial option overrides applied when the pattern matches.
+ *
+ * Use to customize generation for specific operations or schemas. For example, apply different output paths
+ * for different tags, or use custom resolver functions per operation. Can filter by tag, operationId, path,
+ * HTTP method, schema name, or content type.
+ *
+ * @example
+ * ```ts
+ * override: [
+ *   {
+ *     type: 'tag',
+ *     pattern: 'admin',
+ *     options: { output: { path: './src/gen/admin' } }  // admin APIs go to separate folder
+ *   },
+ *   {
+ *     type: 'operationId',
+ *     pattern: 'listPets',
+ *     options: { exclude: true }  // skip this specific operation
+ *   }
+ * ]
+ * ```
+ */
+type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
+  options: Partial<TOptions>;
+};
+type PluginFactoryOptions<
+/**
+ * Unique plugin name.
+ */
+TName extends string = string,
+/**
+ * User-facing plugin options.
+ */
+TOptions extends object = object,
+/**
+ * Plugin options after defaults are applied.
+ */
+TResolvedOptions extends object = TOptions,
+/**
+ * Resolver that encapsulates naming and path-resolution helpers.
+ * Define with `defineResolver` and export alongside the plugin.
+ */
+TResolver extends Resolver = Resolver> = {
+  name: TName;
+  options: TOptions;
+  resolvedOptions: TResolvedOptions;
+  resolver: TResolver;
+};
+/**
+ * Context for hook-style plugin `kubb:plugin:setup` handler.
+ * Provides methods to register generators, configure resolvers, transformers, and renderers.
+ */
+type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
-   * Fires when a plugin starts execution.
+   * Register a generator dynamically. Generators fire during the AST walk (schema/operation/operations)
+   * just like generators declared statically on `createPlugin`.
    */
-  'kubb:plugin:start': [ctx: KubbPluginStartContext];
+  addGenerator<TElement = unknown>(generator: Generator<TFactory, TElement>): void;
   /**
-   * Fires when a plugin completes execution. Duration measured in milliseconds.
+   * Set or override the resolver for this plugin.
+   * The resolver controls file naming and path resolution.
    */
-  'kubb:plugin:end': [ctx: KubbPluginEndContext];
+  setResolver(resolver: Partial<TFactory['resolver']>): void;
   /**
-   * Fires once before plugins execute — allowing plugins to register generators, configure resolvers/transformers/renderers, or inject files.
+   * Set the AST transformer to pre-process nodes before they reach generators.
    */
-  'kubb:plugin:setup': [ctx: KubbPluginSetupContext];
+  setTransformer(visitor: Visitor): void;
   /**
-   * Fires before the plugin execution loop begins. The adapter has already parsed the source and `inputNode` is available.
+   * Set the renderer factory to process JSX elements from generators.
    */
-  'kubb:build:start': [ctx: KubbBuildStartContext];
+  setRenderer(renderer: RendererFactory): void;
   /**
-   * Fires after all plugins run and per-plugin barrels generate, but before files write to disk.
-   * Use this to inject final files that must persist in the same write pass as plugin output.
+   * Set resolved options merged into the normalized plugin's `options`.
+   * Call this in `kubb:plugin:setup` to provide options generators need.
    */
-  'kubb:plugins:end': [ctx: KubbPluginsEndContext];
+  setOptions(options: TFactory['resolvedOptions']): void;
   /**
-   * Fires after all files write to disk.
+   * Inject a raw file into the build output, bypassing the generation pipeline.
    */
-  'kubb:build:end': [ctx: KubbBuildEndContext];
+  injectFile(userFileNode: UserFileNode): void;
   /**
-   * Fires for each schema node during AST traversal. Generator listeners respond to this.
+   * Merge a partial config update into the current build configuration.
    */
-  'kubb:generate:schema': [node: SchemaNode, ctx: GeneratorContext];
+  updateConfig(config: Partial<Config>): void;
   /**
-   * Fires for each operation node during AST traversal. Generator listeners respond to this.
+   * The resolved build configuration at setup time.
    */
-  'kubb:generate:operation': [node: OperationNode, ctx: GeneratorContext];
+  config: Config;
   /**
-   * Fires once after all operations traverse with the full collected array. Batch generator listeners respond to this.
+   * The plugin's user-provided options.
    */
-  'kubb:generate:operations': [nodes: Array<OperationNode>, ctx: GeneratorContext];
-}
-declare global {
-  namespace Kubb {
-    /**
-     * Registry that maps plugin names to their `PluginFactoryOptions`.
-     * Augment this interface in each plugin's `types.ts` to enable automatic
-     * typing for `getPlugin` and `requirePlugin`.
-     *
-     * @example
-     * ```ts
-     * // packages/plugin-ts/src/types.ts
-     * declare global {
-     *   namespace Kubb {
-     *     interface PluginRegistry {
-     *       'plugin-ts': PluginTs
-     *     }
-     *   }
-     * }
-     * ```
-     */
-    interface PluginRegistry {}
-    /**
-     * Extension point for root `Config['output']` options.
-     * Augment the `output` key in middleware or plugin packages to add extra fields
-     * to the global output configuration without touching core types.
-     *
-     * @example
-     * ```ts
-     * // packages/middleware-barrel/src/types.ts
-     * declare global {
-     *   namespace Kubb {
-     *     interface ConfigOptionsRegistry {
-     *       output: {
-     *         barrelType?: import('./types.ts').BarrelType | false
-     *       }
-     *     }
-     *   }
-     * }
-     * ```
-     */
-    interface ConfigOptionsRegistry {}
-    /**
-     * Extension point for per-plugin `Output` options.
-     * Augment the `output` key in middleware or plugin packages to add extra fields
-     * to the per-plugin output configuration without touching core types.
-     *
-     * @example
-     * ```ts
-     * // packages/middleware-barrel/src/types.ts
-     * declare global {
-     *   namespace Kubb {
-     *     interface PluginOptionsRegistry {
-     *       output: {
-     *         barrelType?: import('./types.ts').BarrelType | false
-     *       }
-     *     }
-     *   }
-     * }
-     * ```
-     */
-    interface PluginOptionsRegistry {}
-  }
-}
-//#endregion
-//#region src/defineMiddleware.d.ts
+  options: TFactory['options'];
+};
 /**
- * A middleware instance produced by calling a factory created with `defineMiddleware`.
- * It declares event handlers under a `hooks` object which are registered on the
- * shared emitter after all plugin hooks, so middleware handlers for any event
- * always fire last.
+ * A plugin object produced by `definePlugin`.
+ * Instead of flat lifecycle methods, it groups all handlers under a `hooks:` property
+ * (matching Astro's integration naming convention).
+ *
+ * @template TFactory - The plugin's `PluginFactoryOptions` type.
  */
-type Middleware = {
+type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
-   * Unique identifier for this middleware.
+   * Unique name for the plugin, following the same naming convention as `createPlugin`.
    */
   name: string;
   /**
-   * Lifecycle event handlers for this middleware.
+   * Plugins that must be registered before this plugin executes.
+   * An error is thrown at startup when any listed dependency is missing.
+   */
+  dependencies?: Array<string>;
+  /**
+   * Controls the execution order of this plugin relative to others.
+   *
+   * - `'pre'`  — runs before all normal plugins.
+   * - `'post'` — runs after all normal plugins.
+   * - `undefined` (default) — runs in declaration order among normal plugins.
+   *
+   * Dependency constraints always take precedence over `enforce`.
+   */
+  enforce?: 'pre' | 'post';
+  /**
+   * The options passed by the user when calling the plugin factory.
+   */
+  options?: TFactory['options'];
+  /**
+   * Lifecycle event handlers for this plugin.
    * Any event from the global `KubbHooks` map can be subscribed to here.
-   * Handlers are registered after all plugin handlers, so they always fire last.
    */
-  hooks: { [K in keyof KubbHooks]?: (...args: KubbHooks[K]) => void | Promise<void> };
+  hooks: { [K in keyof KubbHooks as K extends 'kubb:plugin:setup' ? never : K]?: (...args: KubbHooks[K]) => void | Promise<void> } & {
+    'kubb:plugin:setup'?(ctx: KubbPluginSetupContext<TFactory>): void | Promise<void>;
+  };
 };
 /**
- * Creates a middleware factory using the hook-style `hooks` API.
- *
- * Middleware handlers fire after all plugin handlers for any given event, making them ideal for post-processing, logging, and auditing.
- * Per-build state (such as accumulators) belongs inside the factory closure so each `createKubb` invocation gets its own isolated instance.
- *
- * @note The factory can accept typed options. See examples for using options and per-build state patterns.
- *
- * @example
- * ```ts
- * import { defineMiddleware } from '@kubb/core'
- *
- * // Stateless middleware
- * export const logMiddleware = defineMiddleware(() => ({
- *   name: 'log-middleware',
- *   hooks: {
- *     'kubb:build:end'({ files }) {
- *       console.log(`Build complete with ${files.length} files`)
- *     },
- *   },
- * }))
+ * Normalized plugin after setup, with runtime fields populated.
+ * For internal use only — plugins use the public `Plugin` type externally.
  *
- * // Middleware with options and per-build state
- * export const prefixMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
- *   const seen = new Set<string>()
- *   return {
- *     name: 'prefix-middleware',
- *     hooks: {
- *       'kubb:plugin:end'({ plugin }) {
- *         seen.add(`${options.prefix}${plugin.name}`)
- *       },
- *     },
- *   }
- * })
- * ```
+ * @internal
  */
-declare function defineMiddleware<TOptions extends object = object>(factory: (options: TOptions) => Middleware): (options?: TOptions) => Middleware;
-//#endregion
-//#region src/defineParser.d.ts
-type PrintOptions = {
-  extname?: FileNode['extname'];
+type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = Plugin<TOptions> & {
+  options: TOptions['resolvedOptions'] & {
+    output: Output;
+    include?: Array<Include>;
+    exclude: Array<Exclude>;
+    override: Array<Override<TOptions['resolvedOptions']>>;
+  };
+  resolver: TOptions['resolver'];
+  transformer?: Visitor;
+  renderer?: RendererFactory;
+  generators?: Array<Generator>;
+  apply?: (config: Config) => boolean;
+  version?: string;
 };
-type Parser<TMeta extends object = any> = {
-  name: string;
+type KubbPluginStartContext = {
+  plugin: NormalizedPlugin;
+};
+type KubbPluginEndContext = {
+  plugin: NormalizedPlugin;
+  duration: number;
+  success: boolean;
+  error?: Error;
+  config: Config;
   /**
-   * File extensions this parser handles.
-   * Use `undefined` to create a catch-all fallback parser.
-   *
-   * @example Handled extensions
-   * `['.ts', '.js']`
+   * Returns all files currently in the file manager (lazy snapshot).
+   * Includes files added by plugins that have already run.
    */
-  extNames: Array<FileNode['extname']> | undefined;
+  readonly files: ReadonlyArray<FileNode>;
   /**
-   * Convert a resolved file to a string.
+   * Upsert one or more files into the file manager.
    */
-  parse(file: FileNode<TMeta>, options?: PrintOptions): Promise<string> | string;
+  upsertFile: (...files: Array<FileNode>) => void;
 };
 /**
- * Defines a parser with type safety. Creates parsers that transform generated files to strings based on their extension.
+ * Wraps a factory function and returns a typed `Plugin` with lifecycle handlers grouped under `hooks`.
  *
- * @note Call the returned factory with optional options to instantiate the parser.
+ * Handlers live in a single `hooks` object (inspired by Astro integrations).
+ * All lifecycle events from `KubbHooks` are available for subscription.
+ *
+ * @note For real plugins, use a `PluginFactoryOptions` type parameter to get type-safe context in `kubb:plugin:setup`.
+ * Plugin names should follow the convention `plugin-<feature>` (e.g., `plugin-react-query`, `plugin-zod`).
  *
  * @example
  * ```ts
- * import { defineParser } from '@kubb/core'
+ * import { definePlugin } from '@kubb/core'
  *
- * export const jsonParser = defineParser({
- *   name: 'json',
- *   extNames: ['.json'],
- *   parse(file) {
- *     const { extractStringsFromNodes } = await import('@kubb/ast')
- *     return file.sources.map((s) => extractStringsFromNodes(s.nodes ?? [])).join('\n')
+ * export const pluginTs = definePlugin((options: { prefix?: string } = {}) => ({
+ *   name: 'plugin-ts',
+ *   hooks: {
+ *     'kubb:plugin:setup'(ctx) {
+ *       ctx.setResolver(resolverTs)
+ *     },
  *   },
- * })
+ * }))
  * ```
  */
-declare function defineParser<TMeta extends object = any>(parser: Parser<TMeta>): Parser<TMeta>;
+declare function definePlugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>(factory: (options: TFactory['options']) => Plugin<TFactory>): (options?: TFactory['options']) => Plugin<TFactory>;
 //#endregion
-//#region src/types.d.ts
-/**
- * Safely extracts a type from a registry, returning `{}` if the key doesn't exist.
- * Enables optional interface augmentation for `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry`
- * without requiring changes to core.
- *
- * @internal
- */
-type ExtractRegistryKey<T, K extends PropertyKey> = K extends keyof T ? T[K] : {};
-/**
- * Reference to an input file to generate code from.
- *
- * Specify an absolute path or a path relative to the config file location.
- * The adapter will parse this file (e.g., OpenAPI YAML or JSON) into the universal AST.
- */
-type InputPath = {
-  /**
-   * Path to your Swagger/OpenAPI file, absolute or relative to the config file location.
-   *
-   * @example
-   * ```ts
-   * { path: './petstore.yaml' }
-   * { path: '/absolute/path/to/openapi.json' }
-   * ```
-   */
-  path: string;
-};
-/**
- * Inline input data to generate code from.
- *
- * Useful when you want to pass the specification directly instead of from a file.
- * Can be a string (YAML/JSON) or a parsed object.
- */
-type InputData = {
-  /**
-   * Swagger/OpenAPI data as a string (YAML/JSON) or a parsed object.
-   *
-   * @example
-   * ```ts
-   * { data: fs.readFileSync('./openapi.yaml', 'utf8') }
-   * { data: { openapi: '3.1.0', info: { ... } } }
-   * ```
-   */
-  data: string | unknown;
-};
-type Input = InputPath | InputData;
-/**
- * Source data passed to an adapter's `parse` function.
- * Mirrors the config input shape with paths resolved to absolute.
- */
-type AdapterSource = {
-  type: 'path';
-  path: string;
-} | {
-  type: 'data';
-  data: string | unknown;
-} | {
-  type: 'paths';
-  paths: Array<string>;
-};
-/**
- * Generic type parameters for an adapter definition.
- *
- * - `TName` — unique identifier (e.g. `'oas'`, `'asyncapi'`)
- * - `TOptions` — user-facing options passed to the adapter factory
- * - `TResolvedOptions` — options after defaults applied
- * - `TDocument` — type of the parsed source document
- */
-type AdapterFactoryOptions<TName extends string = string, TOptions extends object = object, TResolvedOptions extends object = TOptions, TDocument = unknown> = {
-  name: TName;
-  options: TOptions;
-  resolvedOptions: TResolvedOptions;
-  document: TDocument;
-};
+//#region src/FileManager.d.ts
 /**
- * Adapter that converts input files or data into an `InputNode`.
+ * In-memory file store for generated files.
  *
- * Adapters parse different schema formats (OpenAPI, AsyncAPI, Drizzle, etc.) into Kubb's
- * universal intermediate representation that all plugins consume.
+ * Files with the same `path` are merged — sources, imports, and exports are concatenated.
+ * The `files` getter returns all stored files sorted by path length (shortest first).
  *
  * @example
  * ```ts
- * import { adapterOas } from '@kubb/adapter-oas'
+ * import { FileManager } from '@kubb/core'
  *
- * export default defineConfig({
- *   adapter: adapterOas(),
- *   input: { path: './openapi.yaml' },
- *   plugins: [pluginTs(), pluginZod()],
- * })
+ * const manager = new FileManager()
+ * manager.upsert(myFile)
+ * console.log(manager.files) // all stored files
  * ```
  */
-type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
-  /**
-   * Human-readable adapter identifier (e.g. `'oas'`, `'asyncapi'`).
-   */
-  name: TOptions['name'];
-  /**
-   * Resolved adapter options after defaults have been applied.
-   */
-  options: TOptions['resolvedOptions'];
+declare class FileManager {
+  #private;
   /**
-   * Parsed source document after the first `parse()` call. `null` before parsing.
+   * Adds one or more files. Incoming files with the same path are merged
+   * (sources/imports/exports concatenated), but existing cache entries are
+   * replaced — use {@link upsert} when you want to merge into the cache too.
    */
-  document: TOptions['document'] | null;
-  inputNode: InputNode | null;
+  add(...files: Array<FileNode>): Array<FileNode>;
   /**
-   * Parse the source into a universal `InputNode`.
+   * Adds or merges one or more files.
+   * If a file with the same path already exists in the cache, its
+   * sources/imports/exports are merged into the incoming file.
    */
-  parse: (source: AdapterSource) => PossiblePromise<InputNode>;
+  upsert(...files: Array<FileNode>): Array<FileNode>;
+  getByPath(path: string): FileNode | null;
+  deleteByPath(path: string): void;
+  clear(): void;
   /**
-   * Extract `ImportNode` entries for a schema tree.
-   * Returns an empty array before the first `parse()` call.
-   *
-   * The `resolve` callback receives the collision-corrected schema name and must
-   * return `{ name, path }` for the import, or `undefined` to skip it.
+   * Releases all stored files. Called by the core after `kubb:build:end` to
+   * free the per-plugin FileNode caches for the rest of the process lifetime.
    */
-  getImports: (node: SchemaNode, resolve: (schemaName: string) => {
-    name: string;
-    path: string;
-  }) => Array<ImportNode>;
-};
-type DevtoolsOptions = {
+  dispose(): void;
   /**
-   * Open the AST inspector in Kubb Studio (`/ast`). Defaults to the main Studio page.
-   * @default false
+   * All stored files, sorted by path length (shorter paths first).
    */
-  ast?: boolean;
+  get files(): Array<FileNode>;
+}
+//#endregion
+//#region src/PluginDriver.d.ts
+type Options = {
+  hooks: AsyncEventEmitter<KubbHooks>;
 };
-/**
- * Build configuration for Kubb code generation.
- *
- * The Config is the main entry point for customizing how Kubb generates code. It specifies:
- * - What to generate from (adapter + input)
- * - Where to output generated code (output)
- * - How to generate (plugins + middleware)
- * - Runtime details (parsers, storage, renderer)
- *
- * See `UserConfig` for a relaxed version with sensible defaults.
- *
- * @private
- */
-type Config<TInput = Input> = {
+declare class PluginDriver {
+  #private;
+  readonly config: Config;
+  readonly options: Options;
   /**
-   * Display name for this configuration in CLI output and logs.
-   * Useful when running multiple builds with `defineConfig` arrays.
+   * Returns `'single'` when `fileOrFolder` has a file extension, `'split'` otherwise.
    *
    * @example
    * ```ts
-   * name: 'api-client'
+   * PluginDriver.getMode('src/gen/types.ts')  // 'single'
+   * PluginDriver.getMode('src/gen/types')     // 'split'
    * ```
    */
-  name?: string;
+  static getMode(fileOrFolder: string | undefined | null): 'single' | 'split';
   /**
-   * Project root directory, absolute or relative to the config file.
-   * @default process.cwd()
+   * The universal `@kubb/ast` `InputNode` produced by the adapter, set by
+   * the build pipeline after the adapter's `parse()` resolves.
    */
-  root: string;
+  inputNode: InputNode | undefined;
+  adapter: Adapter | undefined;
   /**
-   * Parsers that convert generated files to strings.
-   * Each parser handles specific extensions (e.g. `.ts`, `.tsx`).
-   * A fallback parser is appended for unhandled extensions.
-   * When omitted, defaults to `parserTs` from `@kubb/parser-ts`.
+   * Central file store for all generated files.
+   * Plugins should use `this.addFile()` / `this.upsertFile()` (via their context) to
+   * add files; this property gives direct read/write access when needed.
+   */
+  readonly fileManager: FileManager;
+  readonly plugins: Map<string, NormalizedPlugin>;
+  constructor(config: Config, options: Options);
+  get hooks(): AsyncEventEmitter<KubbHooks>;
+  /**
+   * Registers a hook-style plugin's lifecycle handlers on the shared `AsyncEventEmitter`.
    *
-   * @default [parserTs] from `@kubb/parser-ts`
-   * @example
-   * ```ts
-   * import { parserTs, tsxParser } from '@kubb/parser-ts'
-   * export default defineConfig({
-   *   parsers: [parserTs, tsxParser],
-   * })
-   * ```
-   */
-  parsers: Array<Parser>;
-  /**
-   * Adapter that parses input files into the universal `InputNode` representation.
-   * Use `@kubb/adapter-oas` for OpenAPI/Swagger or `@kubb/adapter-asyncapi` for other formats.
+   * For `kubb:plugin:setup`, the registered listener wraps the globally emitted context with a
+   * plugin-specific one so that `addGenerator`, `setResolver`, `setTransformer`, and
+   * `setRenderer` all target the correct `normalizedPlugin` entry in the plugins map.
    *
-   * @example
-   * ```ts
-   * import { adapterOas } from '@kubb/adapter-oas'
-   * export default defineConfig({
-   *   adapter: adapterOas(),
-   *   input: { path: './petstore.yaml' },
-   * })
-   * ```
+   * All other hooks are iterated and registered directly as pass-through listeners.
+   * Any event key present in the global `KubbHooks` interface can be subscribed to.
+   *
+   * External tooling can subscribe to any of these events via `hooks.on(...)` to observe
+   * the plugin lifecycle without modifying plugin behavior.
+   *
+   * @internal
    */
-  adapter: Adapter;
+  registerPluginHooks(hookPlugin: Plugin, normalizedPlugin: NormalizedPlugin): void;
   /**
-   * Source file or data to generate code from.
-   * Use `input.path` for a file path or `input.data` for inline data.
+   * Emits the `kubb:plugin:setup` event so that all registered hook-style plugin listeners
+   * can configure generators, resolvers, transformers and renderers before `buildStart` runs.
+   *
+   * Call this once from `safeBuild` before the plugin execution loop begins.
    */
-  input: TInput;
-  output: {
-    /**
-     * Output directory for generated files, absolute or relative to `root`.
-     *
-     * All generated files will be written under this directory. Subdirectories can be created
-     * by plugins based on grouping strategy (by tag, path, etc.).
-     *
-     * @example
-     * ```ts
-     * output: {
-     *   path: './src/gen',  // generates ./src/gen/api.ts, ./src/gen/types.ts, etc.
-     * }
-     * ```
-     */
-    path: string;
-    /**
-     * Remove all files from the output directory before starting the build.
-     *
-     * Useful to ensure old generated files aren't mixed with new ones.
-     * Set to `true` for fresh builds, `false` to preserve manual edits in output dir.
-     *
-     * @default false
-     * @example
-     * ```ts
-     * clean: true  // wipes ./src/gen/* before generating
-     * ```
-     */
-    clean?: boolean;
-    /**
-     * Persists generated files to the file system.
-     *
-     * @default true
-     * @deprecated Use `storage` option to control where files are written instead.
-     */
-    write?: boolean;
-    /**
-     * Auto-format generated files after code generation completes.
-     *
-     * Applies a code formatter to all generated files. Use `'auto'` to detect which formatter
-     * is available on your system. Pass `false` to skip formatting (useful for CI or specific workflows).
-     *
-     * @default false
-     * @example
-     * ```ts
-     * format: 'auto'        // auto-detect prettier, biome, or oxfmt
-     * format: 'prettier'    // force prettier
-     * format: false         // skip formatting
-     * ```
-     */
-    format?: 'auto' | 'prettier' | 'biome' | 'oxfmt' | false;
-    /**
-     * Auto-lint generated files after code generation completes.
-     *
-     * Analyzes all generated files for style/correctness issues. Use `'auto'` to detect which linter
-     * is available on your system. Pass `false` to skip linting.
-     *
-     * @default false
-     * @example
-     * ```ts
-     * lint: 'auto'      // auto-detect oxlint, biome, or eslint
-     * lint: 'eslint'    // force eslint
-     * lint: false       // skip linting
-     * ```
-     */
-    lint?: 'auto' | 'eslint' | 'biome' | 'oxlint' | false;
-    /**
-     * Map file extensions to different output extensions.
-     *
-     * Useful when you want generated `.ts` imports to reference `.js` files or vice versa (e.g., for ESM dual packages).
-     * Keys are the original extension, values are the output extension. Use empty string `''` to omit extension.
-     *
-     * @default { '.ts': '.ts' }
-     * @example
-     * ```ts
-     * extension: { '.ts': '.js' }      // generates import './api.js' instead of './api.ts'
-     * extension: { '.ts': '', '.tsx': '.jsx' }
-     * ```
-     */
-    extension?: Record<FileNode['extname'], FileNode['extname'] | ''>;
-    /**
-     * Banner text prepended to every generated file.
-     *
-     * Useful for auto-generation notices or license headers. Choose a preset or write custom text.
-     * Use `'simple'` for a basic Kubb banner, `'full'` for detailed metadata, or `false` to omit.
-     *
-     * @default 'simple'
-     * @example
-     * ```ts
-     * defaultBanner: 'simple'   // "This file was autogenerated by Kubb"
-     * defaultBanner: 'full'     // adds source, title, description, API version
-     * defaultBanner: false      // no banner
-     * ```
-     */
-    defaultBanner?: 'simple' | 'full' | false;
-    /**
-     * When `true`, overwrites existing files. When `false`, skips generated files that already exist.
-     *
-     * Individual plugins can override this setting. This is useful for preventing accidental data loss
-     * when re-generating while you have local edits in the output folder.
-     *
-     * @default false
-     * @example
-     * ```ts
-     * override: true   // regenerate everything, even existing files
-     * override: false  // skip files that already exist
-     * ```
-     */
-    override?: boolean;
-  } & ExtractRegistryKey<Kubb.ConfigOptionsRegistry, 'output'>;
+  emitSetupHooks(): Promise<void>;
   /**
-   * Storage backend that controls where and how generated files are persisted.
+   * Registers a generator for the given plugin on the shared event emitter.
    *
-   * Defaults to `fsStorage()` which writes to the file system. Pass `memoryStorage()` to keep files in RAM,
-   * or implement a custom `Storage` interface to write to cloud storage, databases, or other backends.
+   * The generator's `schema`, `operation`, and `operations` methods are registered as
+   * listeners on `kubb:generate:schema`, `kubb:generate:operation`, and `kubb:generate:operations`
+   * respectively. Each listener is scoped to the owning plugin via a `ctx.plugin.name` check
+   * so that generators from different plugins do not cross-fire.
    *
-   * @default fsStorage()
-   * @example
-   * ```ts
-   * import { memoryStorage } from '@kubb/core'
+   * The renderer resolution chain is: `generator.renderer → plugin.renderer → config.renderer`.
+   * Set `generator.renderer = null` to explicitly opt out of rendering even when the plugin
+   * declares a renderer.
    *
-   * // Keep generated files in memory (useful for testing, CI pipelines)
-   * storage: memoryStorage()
+   * Call this method inside `addGenerator()` (in `kubb:plugin:setup`) to wire up a generator.
+   */
+  registerGenerator(pluginName: string, gen: Generator): void;
+  /**
+   * Returns `true` when at least one generator was registered for the given plugin
+   * via `addGenerator()` in `kubb:plugin:setup` (event-based path).
    *
-   * // Use custom S3 storage
-   * storage: myS3Storage()
-   * ```
+   * Used by the build loop to decide whether to walk the AST and emit generator events
+   * for a plugin that has no static `plugin.generators`.
+   */
+  hasRegisteredGenerators(pluginName: string): boolean;
+  /**
+   * Unregisters all plugin lifecycle listeners from the shared event emitter.
+   * Called at the end of a build to prevent listener leaks across repeated builds.
    *
-   * @see {@link Storage} interface for implementing custom backends.
+   * @internal
    */
-  storage?: Storage;
+  dispose(): void;
   /**
-   * Plugins that execute during the build to generate code and transform the AST.
+   * Merges `partial` with the plugin's default resolver and stores the result.
+   * Also mirrors it onto `plugin.resolver` so callers using `getPlugin(name).resolver`
+   * get the up-to-date resolver without going through `getResolver()`.
+   */
+  setPluginResolver(pluginName: string, partial: Partial<Resolver>): void;
+  /**
+   * Returns the resolver for the given plugin.
    *
-   * Each plugin processes the AST produced by the adapter and can emit files for different
-   * programming languages or formats (TypeScript, Zod schemas, Faker data, etc.).
-   * Dependencies are enforced — an error is thrown if a plugin requires another plugin that isn't registered.
+   * Resolution order: dynamic resolver set via `setPluginResolver` → static resolver on the
+   * plugin → lazily created default resolver (identity name, no path transforms).
+   */
+  getResolver<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Kubb.PluginRegistry[TName]['resolver'];
+  getResolver<TResolver extends Resolver = Resolver>(pluginName: string): TResolver;
+  getContext<TOptions extends PluginFactoryOptions>(plugin: NormalizedPlugin<TOptions>): GeneratorContext<TOptions> & Record<string, unknown>;
+  getPlugin<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined;
+  getPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(pluginName: string): Plugin<TOptions> | undefined;
+  /**
+   * Like `getPlugin` but throws a descriptive error when the plugin is not found.
+   */
+  requirePlugin<TName extends keyof Kubb.PluginRegistry>(pluginName: TName): Plugin<Kubb.PluginRegistry[TName]>;
+  requirePlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(pluginName: string): Plugin<TOptions>;
+}
+//#endregion
+//#region src/defineGenerator.d.ts
+/**
+ * Context object passed to generator `schema`, `operation`, and `operations` methods.
+ *
+ * The adapter is always defined (guaranteed by `runPluginAstHooks`) so no runtime checks
+ * are needed. `ctx.options` carries resolved per-node options after exclude/include/override
+ * filtering for individual schema/operation calls, or plugin-level options for operations.
+ */
+type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+  config: Config;
+  /**
+   * Absolute path to the current plugin's output directory.
+   */
+  root: string;
+  /**
+   * Determine output mode based on the output config.
+   * Returns `'single'` when `output.path` is a file, `'split'` for a directory.
+   */
+  getMode: (output: {
+    path: string;
+  }) => 'single' | 'split';
+  driver: PluginDriver;
+  /**
+   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
+   */
+  getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined;
+  getPlugin(name: string): Plugin | undefined;
+  /**
+   * Get a plugin by name, throws an error if not found.
+   */
+  requirePlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]>;
+  requirePlugin(name: string): Plugin;
+  /**
+   * Get a resolver by plugin name, typed via `Kubb.PluginRegistry` when registered.
+   */
+  getResolver<TName extends keyof Kubb.PluginRegistry>(name: TName): Kubb.PluginRegistry[TName]['resolver'];
+  getResolver(name: string): Resolver;
+  /**
+   * Add files only if they don't exist.
+   */
+  addFile: (...file: Array<FileNode>) => Promise<void>;
+  /**
+   * Merge sources into the same output file.
+   */
+  upsertFile: (...file: Array<FileNode>) => Promise<void>;
+  hooks: AsyncEventEmitter<KubbHooks>;
+  /**
+   * The current plugin instance.
+   */
+  plugin: Plugin<TOptions>;
+  /**
+   * The current plugin's resolver.
+   */
+  resolver: TOptions['resolver'];
+  /**
+   * The current plugin's transformer.
+   */
+  transformer: Visitor | undefined;
+  /**
+   * Emit a warning.
+   */
+  warn: (message: string) => void;
+  /**
+   * Emit an error.
+   */
+  error: (error: string | Error) => void;
+  /**
+   * Emit an info message.
+   */
+  info: (message: string) => void;
+  /**
+   * Open the current input node in Kubb Studio.
+   */
+  openInStudio: (options?: DevtoolsOptions) => Promise<void>;
+  /**
+   * The configured adapter instance.
+   */
+  adapter: Adapter;
+  /**
+   * The universal `InputNode` produced by the adapter.
+   */
+  inputNode: InputNode;
+  /**
+   * Resolved options after exclude/include/override filtering.
+   */
+  options: TOptions['resolvedOptions'];
+};
+/**
+ * Declares a named generator unit that walks the AST and emits files.
+ *
+ * Each method (`schema`, `operation`, `operations`) is called for the matching node type.
+ * Each method returns `TElement | Array<FileNode> | void`. JSX-based generators require a `renderer` factory.
+ * Return `Array<FileNode>` directly or call `ctx.upsertFile()` manually and return `void` to bypass rendering.
+ *
+ * @note Generators are consumed by plugins and registered via `ctx.addGenerator()` in `kubb:plugin:setup`.
+ *
+ * @example
+ * ```ts
+ * import { defineGenerator } from '@kubb/core'
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
+ *
+ * export const typeGenerator = defineGenerator({
+ *   name: 'typescript',
+ *   renderer: jsxRenderer,
+ *   schema(node, ctx) {
+ *     const { adapter, resolver, root, options } = ctx
+ *     return <File ...><Type node={node} resolver={resolver} /></File>
+ *   },
+ * })
+ * ```
+ */
+type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown> = {
+  /**
+   * Used in diagnostic messages and debug output.
+   */
+  name: string;
+  /**
+   * Optional renderer factory that produces a {@link Renderer} for each render cycle.
    *
-   * Plugins can declare their own options via `PluginFactoryOptions`. See plugin documentation for details.
+   * Generators that return renderer elements (e.g. JSX via `@kubb/renderer-jsx`) must set this
+   * to the matching renderer factory (e.g. `jsxRenderer` from `@kubb/renderer-jsx`).
+   *
+   * Generators that only return `Array<FileNode>` or `void` do not need to set this.
+   *
+   * Set `renderer: null` to explicitly opt out of rendering even when the parent plugin
+   * declares a `renderer` (overrides the plugin-level fallback).
    *
    * @example
    * ```ts
-   * import { pluginTs } from '@kubb/plugin-ts'
-   * import { pluginZod } from '@kubb/plugin-zod'
+   * import { jsxRenderer } from '@kubb/renderer-jsx'
+   * export const myGenerator = defineGenerator<PluginTs>({
+   *   renderer: jsxRenderer,
+   *   schema(node, ctx) { return <File ...>...</File> },
+   * })
+   * ```
+   */
+  renderer?: RendererFactory<TElement> | null;
+  /**
+   * Called for each schema node in the AST walk.
+   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
+   */
+  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>;
+  /**
+   * Called for each operation node in the AST walk.
+   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
+   */
+  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>;
+  /**
+   * Called once after all operations have been walked.
+   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * plus `ctx.options` with the plugin-level options for the batch call.
+   */
+  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>;
+};
+/**
+ * Defines a generator. Returns the object as-is with correct `this` typings.
+ * `applyHookResult` handles renderer elements and `File[]` uniformly using
+ * the generator's declared `renderer` factory.
+ */
+declare function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(generator: Generator<TOptions, TElement>): Generator<TOptions, TElement>;
+//#endregion
+//#region src/createKubb.d.ts
+/**
+ * Safely extracts a type from a registry, returning `{}` if the key doesn't exist.
+ * Enables optional interface augmentation for `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry`
+ * without requiring changes to core.
+ *
+ * @internal
+ */
+type ExtractRegistryKey<T, K extends PropertyKey> = K extends keyof T ? T[K] : {};
+/**
+ * Reference to an input file to generate code from.
+ *
+ * Specify an absolute path or a path relative to the config file location.
+ * The adapter will parse this file (e.g., OpenAPI YAML or JSON) into the universal AST.
+ */
+type InputPath = {
+  /**
+   * Path to your Swagger/OpenAPI file, absolute or relative to the config file location.
    *
-   * plugins: [
-   *   pluginTs({ output: { path: './src/gen' } }),
-   *   pluginZod({ output: { path: './src/gen' } }),
-   * ]
+   * @example
+   * ```ts
+   * { path: './petstore.yaml' }
+   * { path: '/absolute/path/to/openapi.json' }
    * ```
    */
-  plugins: Array<Plugin>;
+  path: string;
+};
+/**
+ * Inline input data to generate code from.
+ *
+ * Useful when you want to pass the specification directly instead of from a file.
+ * Can be a string (YAML/JSON) or a parsed object.
+ */
+type InputData = {
   /**
-   * Middleware instances that observe build events and post-process generated code.
+   * Swagger/OpenAPI data as a string (YAML/JSON) or a parsed object.
    *
-   * Middleware fires AFTER all plugins for each event. Perfect for tasks like:
-   * - Auditing what was generated
-   * - Adding barrel/index files
-   * - Validating output
-   * - Running custom transformations
+   * @example
+   * ```ts
+   * { data: fs.readFileSync('./openapi.yaml', 'utf8') }
+   * { data: { openapi: '3.1.0', info: { ... } } }
+   * ```
+   */
+  data: string | unknown;
+};
+type Input = InputPath | InputData;
+/**
+ * Build configuration for Kubb code generation.
+ *
+ * The Config is the main entry point for customizing how Kubb generates code. It specifies:
+ * - What to generate from (adapter + input)
+ * - Where to output generated code (output)
+ * - How to generate (plugins + middleware)
+ * - Runtime details (parsers, storage, renderer)
+ *
+ * See `UserConfig` for a relaxed version with sensible defaults.
+ *
+ * @private
+ */
+type Config<TInput = Input> = {
+  /**
+   * Display name for this configuration in CLI output and logs.
+   * Useful when running multiple builds with `defineConfig` arrays.
    *
    * @example
    * ```ts
-   * import { middlewareBarrel } from '@kubb/middleware-barrel'
-   *
-   * middleware: [middlewareBarrel()]
+   * name: 'api-client'
    * ```
-   *
-   * @see {@link defineMiddleware} to create custom middleware.
    */
-  middleware?: Array<Middleware>;
+  name?: string;
+  /**
+   * Project root directory, absolute or relative to the config file.
+   * @default process.cwd()
+   */
+  root: string;
   /**
-   * Default renderer factory used by all plugins and generators.
-   * Resolution chain: `generator.renderer` → `plugin.renderer` → `config.renderer` → `undefined` (raw FileNode[] mode).
+   * Parsers that convert generated files to strings.
+   * Each parser handles specific extensions (e.g. `.ts`, `.tsx`).
+   * A fallback parser is appended for unhandled extensions.
+   * When omitted, defaults to `parserTs` from `@kubb/parser-ts`.
    *
+   * @default [parserTs] from `@kubb/parser-ts`
    * @example
    * ```ts
-   * import { jsxRenderer } from '@kubb/renderer-jsx'
+   * import { parserTs, tsxParser } from '@kubb/parser-ts'
    * export default defineConfig({
-   *   renderer: jsxRenderer,
-   *   plugins: [pluginTs(), pluginZod()],
+   *   parsers: [parserTs, tsxParser],
    * })
    * ```
    */
+  parsers: Array<Parser>;
   /**
-   * Renderer that converts generated AST nodes to code strings.
+   * Adapter that parses input files into the universal `InputNode` representation.
+   * Use `@kubb/adapter-oas` for OpenAPI/Swagger or `@kubb/adapter-asyncapi` for other formats.
    *
-   * By default, Kubb uses the JSX renderer (`rendererJsx`). Pass a custom renderer to support
-   * different output formats (template engines, code generation DSLs, etc.).
+   * When omitted, Kubb runs in plugin-only mode: `kubb:plugin:setup` fires and files
+   * injected via `injectFile` are written, but no AST walk occurs and generator hooks
+   * (`kubb:generate:schema`, `kubb:generate:operation`) are never emitted.
    *
-   * @default rendererJsx()  // from @kubb/renderer-jsx
    * @example
    * ```ts
-   * import { rendererJsx } from '@kubb/renderer-jsx'
-   * renderer: rendererJsx()
+   * import { adapterOas } from '@kubb/adapter-oas'
+   * export default defineConfig({
+   *   adapter: adapterOas(),
+   *   input: { path: './petstore.yaml' },
+   * })
    * ```
-   *
-   * @see {@link Renderer} to implement a custom renderer.
    */
-  renderer?: RendererFactory;
+  adapter?: Adapter;
   /**
-   * Kubb Studio cloud integration settings.
-   *
-   * Kubb Studio (https://studio.kubb.dev) is a web-based IDE for managing API specs and generated code.
-   * Set to `true` to enable with default settings, or pass an object to customize the Studio URL.
-   *
-   * @default false  // disabled by default
-   * @example
-   * ```ts
-   * devtools: true                                   // use default Kubb Studio
-   * devtools: { studioUrl: 'https://my-studio.dev' } // custom Studio instance
-   * ```
+   * Source file or data to generate code from.
+   * Use `input.path` for a file path or `input.data` for inline data.
+   * Required when an adapter is configured; omit when running in plugin-only mode.
    */
-  devtools?: true | {
+  input?: TInput;
+  output: {
     /**
-     * Override the Kubb Studio base URL.
-     * @default 'https://studio.kubb.dev'
+     * Output directory for generated files, absolute or relative to `root`.
+     *
+     * All generated files will be written under this directory. Subdirectories can be created
+     * by plugins based on grouping strategy (by tag, path, etc.).
+     *
+     * @example
+     * ```ts
+     * output: {
+     *   path: './src/gen',  // generates ./src/gen/api.ts, ./src/gen/types.ts, etc.
+     * }
+     * ```
      */
-    studioUrl?: typeof DEFAULT_STUDIO_URL | (string & {});
-  };
-  /**
-   * Lifecycle hooks that execute during or after the build process.
-   *
-   * Hooks allow you to run external tools (prettier, eslint, custom scripts) based on build events.
-   * Currently supports the `done` hook which fires after all plugins and middleware complete.
-   *
-   * @example
-   * ```ts
-   * hooks: {
-   *   done: 'prettier --write "./src/gen"',      // auto-format generated files
-   *   // or multiple commands:
-   *   done: ['prettier --write "./src/gen"', 'eslint --fix "./src/gen"']
-   * }
-   * ```
-   */
-  hooks?: {
+    path: string;
     /**
-     * Command(s) to run after all plugins and middleware complete generation.
+     * Remove all files from the output directory before starting the build.
      *
-     * Useful for post-processing: formatting, linting, copying files, or custom validation.
-     * Pass a single command string or array of command strings to run sequentially.
-     * Commands are executed relative to the `root` directory.
+     * Useful to ensure old generated files aren't mixed with new ones.
+     * Set to `true` for fresh builds, `false` to preserve manual edits in output dir.
      *
+     * @default false
      * @example
      * ```ts
-     * done: 'prettier --write "./src/gen"'
-     * done: ['prettier --write "./src/gen"', 'eslint --fix "./src/gen"']
+     * clean: true  // wipes ./src/gen/* before generating
      * ```
      */
-    done?: string | Array<string>;
-  };
-};
-/**
- * Type/string pattern filter for include/exclude/override matching.
- */
-type PatternFilter = {
-  type: string;
-  pattern: string | RegExp;
-};
-/**
- * Pattern filter with partial option overrides applied when the pattern matches.
- */
-type PatternOverride<TOptions> = PatternFilter & {
-  options: Omit<Partial<TOptions>, 'override'>;
-};
-/**
- * Context for resolving filtered options for a given operation or schema node.
- *
- * @internal
- */
-type ResolveOptionsContext<TOptions> = {
-  options: TOptions;
-  exclude?: Array<PatternFilter>;
-  include?: Array<PatternFilter>;
-  override?: Array<PatternOverride<TOptions>>;
-};
-/**
- * Base constraint for all plugin resolver objects.
- *
- * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
- * are injected automatically by `defineResolver` — extend this type to add custom resolution methods.
- *
- * @example
- * ```ts
- * type MyResolver = Resolver & {
- *   resolveName(node: SchemaNode): string
- *   resolveTypedName(node: SchemaNode): string
- * }
- * ```
- */
-type Resolver = {
-  name: string;
-  pluginName: Plugin['name'];
-  default(name: string, type?: 'file' | 'function' | 'type' | 'const'): string;
-  resolveOptions<TOptions>(node: Node, context: ResolveOptionsContext<TOptions>): TOptions | null;
-  resolvePath(params: ResolverPathParams, context: ResolverContext): string;
-  resolveFile(params: ResolverFileParams, context: ResolverContext): FileNode;
-  resolveBanner(node: InputNode | null, context: ResolveBannerContext): string | undefined;
-  resolveFooter(node: InputNode | null, context: ResolveBannerContext): string | undefined;
-};
-type PluginFactoryOptions<
-/**
- * Unique plugin name.
- */
-TName extends string = string,
-/**
- * User-facing plugin options.
- */
-TOptions extends object = object,
-/**
- * Plugin options after defaults are applied.
- */
-TResolvedOptions extends object = TOptions,
-/**
- * Resolver that encapsulates naming and path-resolution helpers.
- * Define with `defineResolver` and export alongside the plugin.
- */
-TResolver extends Resolver = Resolver> = {
-  name: TName;
-  options: TOptions;
-  resolvedOptions: TResolvedOptions;
-  resolver: TResolver;
-};
-/**
- * Normalized plugin after setup, with runtime fields populated.
- * For internal use only — plugins use the public `Plugin` type externally.
- *
- * @internal
- */
-type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = Plugin<TOptions> & {
-  options: TOptions['resolvedOptions'] & {
-    output: Output;
-    include?: Array<Include>;
-    exclude: Array<Exclude$1>;
-    override: Array<Override<TOptions['resolvedOptions']>>;
-  };
-  resolver: TOptions['resolver'];
-  transformer?: Visitor;
-  renderer?: RendererFactory;
-  generators?: Array<Generator>;
-  apply?: (config: Config) => boolean;
-  version?: string;
-};
-/**
- * Partial `Config` for user-facing entry points with sensible defaults.
- *
- * `UserConfig` is what you pass to `defineConfig()`. It has optional `root`, `plugins`, `parsers`, and `adapter`
- * fields (which fall back to sensible defaults). All other Config options are available, including `output`, `input`,
- * `storage`, `middleware`, `renderer`, `devtools`, and `hooks`.
- *
- * @example
- * ```ts
- * export default defineConfig({
- *   input: { path: './petstore.yaml' },
- *   output: { path: './src/gen' },
- *   plugins: [pluginTs(), pluginZod()],
- * })
- * ```
- */
-type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter'> & {
+    clean?: boolean;
+    /**
+     * Auto-format generated files after code generation completes.
+     *
+     * Applies a code formatter to all generated files. Use `'auto'` to detect which formatter
+     * is available on your system. Pass `false` to skip formatting (useful for CI or specific workflows).
+     *
+     * @default false
+     * @example
+     * ```ts
+     * format: 'auto'        // auto-detect prettier, biome, or oxfmt
+     * format: 'prettier'    // force prettier
+     * format: false         // skip formatting
+     * ```
+     */
+    format?: 'auto' | 'prettier' | 'biome' | 'oxfmt' | false;
+    /**
+     * Auto-lint generated files after code generation completes.
+     *
+     * Analyzes all generated files for style/correctness issues. Use `'auto'` to detect which linter
+     * is available on your system. Pass `false` to skip linting.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * lint: 'auto'      // auto-detect oxlint, biome, or eslint
+     * lint: 'eslint'    // force eslint
+     * lint: false       // skip linting
+     * ```
+     */
+    lint?: 'auto' | 'eslint' | 'biome' | 'oxlint' | false;
+    /**
+     * Map file extensions to different output extensions.
+     *
+     * Useful when you want generated `.ts` imports to reference `.js` files or vice versa (e.g., for ESM dual packages).
+     * Keys are the original extension, values are the output extension. Use empty string `''` to omit extension.
+     *
+     * @default { '.ts': '.ts' }
+     * @example
+     * ```ts
+     * extension: { '.ts': '.js' }      // generates import './api.js' instead of './api.ts'
+     * extension: { '.ts': '', '.tsx': '.jsx' }
+     * ```
+     */
+    extension?: Record<FileNode['extname'], FileNode['extname'] | ''>;
+    /**
+     * Banner text prepended to every generated file.
+     *
+     * Useful for auto-generation notices or license headers. Choose a preset or write custom text.
+     * Use `'simple'` for a basic Kubb banner, `'full'` for detailed metadata, or `false` to omit.
+     *
+     * @default 'simple'
+     * @example
+     * ```ts
+     * defaultBanner: 'simple'   // "This file was autogenerated by Kubb"
+     * defaultBanner: 'full'     // adds source, title, description, API version
+     * defaultBanner: false      // no banner
+     * ```
+     */
+    defaultBanner?: 'simple' | 'full' | false;
+    /**
+     * When `true`, overwrites existing files. When `false`, skips generated files that already exist.
+     *
+     * Individual plugins can override this setting. This is useful for preventing accidental data loss
+     * when re-generating while you have local edits in the output folder.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * override: true   // regenerate everything, even existing files
+     * override: false  // skip files that already exist
+     * ```
+     */
+    override?: boolean;
+  } & ExtractRegistryKey<Kubb$1.ConfigOptionsRegistry, 'output'>;
   /**
-   * Project root directory, absolute or relative to the config file location.
+   * Storage backend that controls where and how generated files are persisted.
    *
-   * Used as the base path for `root`-relative paths (e.g., `output.path`, file paths in hooks).
+   * Defaults to `fsStorage()` which writes to the file system. Pass `memoryStorage()` to keep files in RAM,
+   * or implement a custom `Storage` interface to write to cloud storage, databases, or other backends.
    *
-   * @default process.cwd()
+   * @default fsStorage()
    * @example
    * ```ts
-   * root: '/home/user/my-project'
-   * root: './my-project'  // relative to config file
+   * import { memoryStorage } from '@kubb/core'
+   *
+   * // Keep generated files in memory (useful for testing, CI pipelines)
+   * storage: memoryStorage()
+   *
+   * // Use custom S3 storage
+   * storage: myS3Storage()
    * ```
+   *
+   * @see {@link Storage} interface for implementing custom backends.
    */
-  root?: string;
+  storage: Storage;
   /**
-   * Custom parsers that convert generated AST nodes to strings (TypeScript, JSON, markdown, etc.).
+   * Plugins that execute during the build to generate code and transform the AST.
+   *
+   * Each plugin processes the AST produced by the adapter and can emit files for different
+   * programming languages or formats (TypeScript, Zod schemas, Faker data, etc.).
+   * Dependencies are enforced — an error is thrown if a plugin requires another plugin that isn't registered.
    *
-   * Each parser handles a specific file type. By default, Kubb uses `parserTs` from `@kubb/parser-ts` for TypeScript files.
-   * Pass custom parsers to support additional languages or custom formats.
+   * Plugins can declare their own options via `PluginFactoryOptions`. See plugin documentation for details.
    *
-   * @default [parserTs]  // from @kubb/parser-ts
    * @example
    * ```ts
-   * import { parserTs } from '@kubb/parser-ts'
-   * import { parserJsonSchema } from '@kubb/parser-json-schema'
+   * import { pluginTs } from '@kubb/plugin-ts'
+   * import { pluginZod } from '@kubb/plugin-zod'
    *
-   * parsers: [parserTs(), parserJsonSchema()]
+   * plugins: [
+   *   pluginTs({ output: { path: './src/gen' } }),
+   *   pluginZod({ output: { path: './src/gen' } }),
+   * ]
    * ```
-   *
-   * @see {@link Parser} to implement a custom parser.
    */
-  parsers?: Array<Parser>;
+  plugins: Array<Plugin>;
   /**
-   * Adapter that parses your API specification (OpenAPI, GraphQL, AsyncAPI, etc.) into Kubb's universal AST.
+   * Middleware instances that observe build events and post-process generated code.
    *
-   * The adapter bridge between your input format and Kubb's internal representation. By default, uses the OAS adapter.
-   * Pass an alternative adapter (or multiple configs with different adapters) to support different spec formats.
+   * Middleware fires AFTER all plugins for each event. Perfect for tasks like:
+   * - Auditing what was generated
+   * - Adding barrel/index files
+   * - Validating output
+   * - Running custom transformations
    *
-   * @default new OasAdapter()  // from @kubb/adapter-oas
    * @example
    * ```ts
-   * import { Oas } from '@kubb/adapter-oas'
+   * import { middlewareBarrel } from '@kubb/middleware-barrel'
    *
-   * adapter: new Oas({ apiVersion: '3.0.0' })
+   * middleware: [middlewareBarrel()]
    * ```
    *
-   * @see {@link Adapter} to implement a custom adapter for GraphQL or other formats.
+   * @see {@link defineMiddleware} to create custom middleware.
    */
-  adapter?: Adapter;
+  middleware?: Array<Middleware>;
   /**
-   * Plugins that execute during the build to generate code and transform the AST.
+   * Renderer that converts generated AST nodes to code strings.
    *
-   * Each plugin processes the AST produced by the adapter and can emit files for different
-   * programming languages or formats (TypeScript, Zod schemas, Faker data, etc.).
+   * By default, Kubb uses the JSX renderer (`rendererJsx`). Pass a custom renderer to support
+   * different output formats (template engines, code generation DSLs, etc.).
    *
-   * @default []  // no plugins (useful for setup/testing)
+   * @default rendererJsx()  // from @kubb/renderer-jsx
    * @example
    * ```ts
-   * plugins: [
-   *   pluginTs({ output: { path: './src/gen' } }),
-   *   pluginZod({ output: { path: './src/gen' } }),
-   * ]
+   * import { rendererJsx } from '@kubb/renderer-jsx'
+   * renderer: rendererJsx()
    * ```
    *
-   * @see {@link definePlugin} to create a custom plugin.
-   */
-  plugins?: Array<Plugin>;
-};
-type ResolveNameParams = {
-  name: string;
-  pluginName?: string;
-  /**
-   * Entity type being named.
-   * - `'file'` — file name (camelCase)
-   * - `'function'` — exported function name (camelCase)
-   * - `'type'` — TypeScript type name (PascalCase)
-   * - `'const'` — variable name (camelCase)
-   */
-  type?: 'file' | 'function' | 'type' | 'const';
-};
-/**
- * Context object passed to generator `schema`, `operation`, and `operations` methods.
- *
- * The adapter is always defined (guaranteed by `runPluginAstHooks`) so no runtime checks
- * are needed. `ctx.options` carries resolved per-node options after exclude/include/override
- * filtering for individual schema/operation calls, or plugin-level options for operations.
- */
-type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
-  config: Config;
-  /**
-   * Absolute path to the current plugin's output directory.
-   */
-  root: string;
-  /**
-   * Determine output mode based on the output config.
-   * Returns `'single'` when `output.path` is a file, `'split'` for a directory.
-   */
-  getMode: (output: {
-    path: string;
-  }) => 'single' | 'split';
-  driver: PluginDriver;
-  /**
-   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
-   */
-  getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined;
-  getPlugin(name: string): Plugin | undefined;
-  /**
-   * Get a plugin by name, throws an error if not found.
-   */
-  requirePlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]>;
-  requirePlugin(name: string): Plugin;
-  /**
-   * Get a resolver by plugin name, typed via `Kubb.PluginRegistry` when registered.
-   */
-  getResolver<TName extends keyof Kubb.PluginRegistry>(name: TName): Kubb.PluginRegistry[TName]['resolver'];
-  getResolver(name: string): Resolver;
-  /**
-   * Add files only if they don't exist.
-   */
-  addFile: (...file: Array<FileNode>) => Promise<void>;
-  /**
-   * Merge sources into the same output file.
-   */
-  upsertFile: (...file: Array<FileNode>) => Promise<void>;
-  hooks: AsyncEventEmitter<KubbHooks>;
-  /**
-   * The current plugin instance.
-   */
-  plugin: Plugin<TOptions>;
-  /**
-   * The current plugin's resolver.
-   */
-  resolver: TOptions['resolver'];
-  /**
-   * The current plugin's transformer.
-   */
-  transformer: Visitor | undefined;
-  /**
-   * Emit a warning.
-   */
-  warn: (message: string) => void;
-  /**
-   * Emit an error.
-   */
-  error: (error: string | Error) => void;
-  /**
-   * Emit an info message.
-   */
-  info: (message: string) => void;
-  /**
-   * Open the current input node in Kubb Studio.
-   */
-  openInStudio: (options?: DevtoolsOptions) => Promise<void>;
-  /**
-   * The configured adapter instance.
-   */
-  adapter: Adapter;
-  /**
-   * The universal `InputNode` produced by the adapter.
-   */
-  inputNode: InputNode;
-  /**
-   * Resolved options after exclude/include/override filtering.
-   */
-  options: TOptions['resolvedOptions'];
-};
-/**
- * Output configuration for generated files.
- */
-type Output<_TOptions = unknown> = {
-  /**
-   * Output folder or file path for generated code.
-   */
-  path: string;
-  /**
-   * Text or function prepended to every generated file.
-   * When a function, receives the current `InputNode` and returns a string.
-   */
-  banner?: string | ((node?: InputNode) => string);
-  /**
-   * Text or function appended to every generated file.
-   * When a function, receives the current `InputNode` and returns a string.
-   */
-  footer?: string | ((node?: InputNode) => string);
-  /**
-   * Whether to override existing external files if they already exist.
-   * @default false
-   */
-  override?: boolean;
-} & ExtractRegistryKey<Kubb.PluginOptionsRegistry, 'output'>;
-type Group = {
-  /**
-   * How to group files into subdirectories.
-   * - `'tag'` — group by OpenAPI tags
-   * - `'path'` — group by OpenAPI paths
-   */
-  type: 'tag' | 'path';
-  /**
-   * Function that returns the subdirectory name for a group value.
-   * Defaults to `${camelCase(group)}Controller` for tags, first path segment for paths.
-   */
-  name?: (context: {
-    group: string;
-  }) => string;
-};
-type LoggerOptions = {
-  /**
-   * Log level for output verbosity.
-   * @default 3
-   */
-  logLevel: (typeof logLevel)[keyof typeof logLevel];
-};
-/**
- * Shared context passed to plugins, parsers, and other internals.
- */
-type LoggerContext = AsyncEventEmitter<KubbHooks>;
-type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
-  name: string;
-  install: (context: LoggerContext, options?: TOptions) => void | Promise<void>;
-};
-type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Logger<TOptions>;
-/**
- * Context for hook-style plugin `kubb:plugin:setup` handler.
- * Provides methods to register generators, configure resolvers, transformers, and renderers.
- */
-type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
-  /**
-   * Register a generator dynamically. Generators fire during the AST walk (schema/operation/operations)
-   * just like generators declared statically on `createPlugin`.
-   */
-  addGenerator<TElement = unknown>(generator: Generator<TFactory, TElement>): void;
-  /**
-   * Set or override the resolver for this plugin.
-   * The resolver controls file naming and path resolution.
+   * @see {@link Renderer} to implement a custom renderer.
    */
-  setResolver(resolver: Partial<TFactory['resolver']>): void;
+  renderer?: RendererFactory;
   /**
-   * Set the AST transformer to pre-process nodes before they reach generators.
+   * Kubb Studio cloud integration settings.
+   *
+   * Kubb Studio (https://kubb.studio) is a web-based IDE for managing API specs and generated code.
+   * Set to `true` to enable with default settings, or pass an object to customize the Studio URL.
+   *
+   * @default false  // disabled by default
+   * @example
+   * ```ts
+   * devtools: true                                   // use default Kubb Studio
+   * devtools: { studioUrl: 'https://my-studio.dev' } // custom Studio instance
+   * ```
    */
-  setTransformer(visitor: Visitor): void;
+  devtools?: true | {
+    /**
+     * Override the Kubb Studio base URL.
+     * @default 'https://kubb.studio'
+     */
+    studioUrl?: typeof DEFAULT_STUDIO_URL | (string & {});
+  };
   /**
-   * Set the renderer factory to process JSX elements from generators.
+   * Lifecycle hooks that execute during or after the build process.
+   *
+   * Hooks allow you to run external tools (prettier, eslint, custom scripts) based on build events.
+   * Currently supports the `done` hook which fires after all plugins and middleware complete.
+   *
+   * @example
+   * ```ts
+   * hooks: {
+   *   done: 'prettier --write "./src/gen"',      // auto-format generated files
+   *   // or multiple commands:
+   *   done: ['prettier --write "./src/gen"', 'eslint --fix "./src/gen"']
+   * }
+   * ```
    */
-  setRenderer(renderer: RendererFactory): void;
+  hooks?: {
+    /**
+     * Command(s) to run after all plugins and middleware complete generation.
+     *
+     * Useful for post-processing: formatting, linting, copying files, or custom validation.
+     * Pass a single command string or array of command strings to run sequentially.
+     * Commands are executed relative to the `root` directory.
+     *
+     * @example
+     * ```ts
+     * done: 'prettier --write "./src/gen"'
+     * done: ['prettier --write "./src/gen"', 'eslint --fix "./src/gen"']
+     * ```
+     */
+    done?: string | Array<string>;
+  };
+};
+/**
+ * Partial `Config` for user-facing entry points with sensible defaults.
+ *
+ * `UserConfig` is what you pass to `defineConfig()`. It has optional `root`, `plugins`, `parsers`, and `adapter`
+ * fields (which fall back to sensible defaults). All other Config options are available, including `output`, `input`,
+ * `storage`, `middleware`, `renderer`, `devtools`, and `hooks`.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   input: { path: './petstore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [pluginTs(), pluginZod()],
+ * })
+ * ```
+ */
+type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter' | 'storage'> & {
   /**
-   * Set resolved options merged into the normalized plugin's `options`.
-   * Call this in `kubb:plugin:setup` to provide options generators need.
+   * Project root directory, absolute or relative to the config file location.
+   * @default process.cwd()
    */
-  setOptions(options: TFactory['resolvedOptions']): void;
+  root?: string;
   /**
-   * Inject a raw file into the build output, bypassing the generation pipeline.
+   * Custom parsers that convert generated AST nodes to strings (TypeScript, JSON, markdown, etc.).
+   * @default [parserTs]  // from `@kubb/parser-ts`
    */
-  injectFile(userFileNode: UserFileNode): void;
+  parsers?: Array<Parser>;
   /**
-   * Merge a partial config update into the current build configuration.
+   * Adapter that parses your API specification into Kubb's universal AST.
+   * When omitted, Kubb runs in plugin-only mode.
    */
-  updateConfig(config: Partial<Config>): void;
+  adapter?: Adapter;
   /**
-   * The resolved build configuration at setup time.
+   * Plugins that execute during the build to generate code and transform the AST.
+   * @default []
    */
-  config: Config;
+  plugins?: Array<Plugin>;
   /**
-   * The plugin's user-provided options.
+   * Storage backend that controls where and how generated files are persisted.
+   * @default fsStorage()
    */
-  options: TFactory['options'];
+  storage?: Storage;
 };
+declare global {
+  namespace Kubb {
+    /**
+     * Registry that maps plugin names to their `PluginFactoryOptions`.
+     * Augment this interface in each plugin's `types.ts` to enable automatic
+     * typing for `getPlugin` and `requirePlugin`.
+     *
+     * @example
+     * ```ts
+     * // packages/plugin-ts/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface PluginRegistry {
+     *       'plugin-ts': PluginTs
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface PluginRegistry {}
+    /**
+     * Extension point for root `Config['output']` options.
+     * Augment the `output` key in middleware or plugin packages to add extra fields
+     * to the global output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/middleware-barrel/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface ConfigOptionsRegistry {
+     *       output: {
+     *         barrel?: import('./types.ts').BarrelConfig | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface ConfigOptionsRegistry {}
+    /**
+     * Extension point for per-plugin `Output` options.
+     * Augment the `output` key in middleware or plugin packages to add extra fields
+     * to the per-plugin output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/middleware-barrel/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface PluginOptionsRegistry {
+     *       output: {
+     *         barrel?: import('./types.ts').PluginBarrelConfig | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface PluginOptionsRegistry {}
+  }
+}
 /**
- * Context for hook-style plugin `kubb:build:start` handler.
- * Fires immediately before the plugin execution loop begins.
+ * Lifecycle events emitted during Kubb code generation.
+ * Use these for logging, progress tracking, and custom integrations.
+ *
+ * @example
+ * ```typescript
+ * import type { AsyncEventEmitter } from '@internals/utils'
+ * import type { KubbHooks } from '@kubb/core'
+ *
+ * const hooks: AsyncEventEmitter<KubbHooks> = new AsyncEventEmitter()
+ *
+ * hooks.on('kubb:lifecycle:start', () => {
+ *   console.log('Starting Kubb generation')
+ * })
+ *
+ * hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
+ *   console.log(`Plugin ${plugin.name} completed in ${duration}ms`)
+ * })
+ * ```
  */
+interface KubbHooks {
+  'kubb:lifecycle:start': [ctx: KubbLifecycleStartContext];
+  'kubb:lifecycle:end': [];
+  'kubb:config:start': [];
+  'kubb:config:end': [ctx: KubbConfigEndContext];
+  'kubb:generation:start': [ctx: KubbGenerationStartContext];
+  'kubb:generation:end': [ctx: KubbGenerationEndContext];
+  'kubb:generation:summary': [ctx: KubbGenerationSummaryContext];
+  'kubb:format:start': [];
+  'kubb:format:end': [];
+  'kubb:lint:start': [];
+  'kubb:lint:end': [];
+  'kubb:hooks:start': [];
+  'kubb:hooks:end': [];
+  'kubb:hook:start': [ctx: KubbHookStartContext];
+  'kubb:hook:end': [ctx: KubbHookEndContext];
+  'kubb:version:new': [ctx: KubbVersionNewContext];
+  'kubb:info': [ctx: KubbInfoContext];
+  'kubb:error': [ctx: KubbErrorContext];
+  'kubb:success': [ctx: KubbSuccessContext];
+  'kubb:warn': [ctx: KubbWarnContext];
+  'kubb:debug': [ctx: KubbDebugContext];
+  'kubb:files:processing:start': [ctx: KubbFilesProcessingStartContext];
+  'kubb:file:processing:update': [ctx: KubbFileProcessingUpdateContext];
+  'kubb:files:processing:end': [ctx: KubbFilesProcessingEndContext];
+  'kubb:plugin:start': [ctx: KubbPluginStartContext];
+  'kubb:plugin:end': [ctx: KubbPluginEndContext];
+  'kubb:plugin:setup': [ctx: KubbPluginSetupContext];
+  'kubb:build:start': [ctx: KubbBuildStartContext];
+  'kubb:plugins:end': [ctx: KubbPluginsEndContext];
+  'kubb:build:end': [ctx: KubbBuildEndContext];
+  'kubb:generate:schema': [node: SchemaNode, ctx: GeneratorContext];
+  'kubb:generate:operation': [node: OperationNode, ctx: GeneratorContext];
+  'kubb:generate:operations': [nodes: Array<OperationNode>, ctx: GeneratorContext];
+}
 type KubbBuildStartContext = {
   config: Config;
   adapter: Adapter;
   inputNode: InputNode;
-  /**
-   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
-   */
-  getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined;
+  getPlugin<TName extends keyof Kubb$1.PluginRegistry>(name: TName): Plugin<Kubb$1.PluginRegistry[TName]> | undefined;
   getPlugin(name: string): Plugin | undefined;
-  /**
-   * Get all files currently in the file manager.
-   * Call this lazily (e.g. in `kubb:plugin:end`) to see files added by prior plugins.
-   */
   readonly files: ReadonlyArray<FileNode>;
-  /**
-   * Upsert one or more files into the file manager.
-   * Files with the same path are merged; new files are appended.
-   * Safe to call at any point during the plugin lifecycle, including inside `kubb:plugin:end`.
-   */
   upsertFile: (...files: Array<FileNode>) => void;
 };
-/**
- * Context for `kubb:plugins:end` handlers.
- * Fires after plugins run and per-plugin barrels are written, before final write to disk.
- * Middleware that needs final files (e.g. root barrel) use this event.
- */
 type KubbPluginsEndContext = {
   config: Config;
-  /**
-   * All files currently in the file manager (lazy snapshot).
-   */
   readonly files: ReadonlyArray<FileNode>;
-  /**
-   * Upsert files into the file manager.
-   * Files added here are included in the write pass.
-   */
   upsertFile: (...files: Array<FileNode>) => void;
 };
-/**
- * Context for hook-style plugin `kubb:build:end` handler.
- * Fires after all files have been written to disk.
- */
 type KubbBuildEndContext = {
   files: Array<FileNode>;
   config: Config;
@@ -1804,8 +1955,25 @@ type KubbGenerationStartContext = {
 };
 type KubbGenerationEndContext = {
   config: Config;
-  files: Array<FileNode>;
-  sources: Map<string, string>;
+  /**
+   * Read-only view of the files Kubb wrote during this build.
+   *
+   * Keys are scoped to this run; files from earlier builds are not included.
+   * Reads go directly to `config.storage`, so nothing is buffered in memory.
+   *
+   * @example Read a generated file
+   * ```ts
+   * const code = await storage.getItem('/src/gen/pet.ts')
+   * ```
+   *
+   * @example Walk every generated file
+   * ```ts
+   * for (const path of await storage.getKeys()) {
+   *   const code = await storage.getItem(path)
+   * }
+   * ```
+   */
+  storage: Storage;
 };
 type KubbGenerationSummaryContext = {
   config: Config;
@@ -1847,53 +2015,16 @@ type KubbFilesProcessingStartContext = {
   files: Array<FileNode>;
 };
 type KubbFileProcessingUpdateContext = {
-  /**
-   * Number of files processed.
-   */
   processed: number;
-  /**
-   * Total files to process.
-   */
   total: number;
-  /**
-   * Processing percentage (0–100).
-   */
   percentage: number;
-  /**
-   * Optional source identifier.
-   */
   source?: string;
-  /**
-   * The file being processed.
-   */
   file: FileNode;
-  /**
-   * The current build configuration.
-   */
   config: Config;
 };
 type KubbFilesProcessingEndContext = {
   files: Array<FileNode>;
 };
-type KubbPluginStartContext = {
-  plugin: NormalizedPlugin;
-};
-type KubbPluginEndContext = {
-  plugin: NormalizedPlugin;
-  duration: number;
-  success: boolean;
-  error?: Error;
-  config: Config;
-  /**
-   * Returns all files currently in the file manager (lazy snapshot).
-   * Includes files added by plugins that have already run.
-   */
-  readonly files: ReadonlyArray<FileNode>;
-  /**
-   * Upsert one or more files into the file manager.
-   */
-  upsertFile: (...files: Array<FileNode>) => void;
-};
 type KubbHookStartContext = {
   id?: string;
   command: string;
@@ -1906,243 +2037,140 @@ type KubbHookEndContext = {
   success: boolean;
   error: Error | null;
 };
-type ByTag = {
-  /**
-   * Filter by OpenAPI `tags` field. Matches one or more tags assigned to operations.
-   */
-  type: 'tag';
+/**
+ * CLI options derived from command-line flags.
+ */
+type CLIOptions = {
+  config?: string;
+  watch?: boolean; /** @default 'silent' */
+  logLevel?: 'silent' | 'info' | 'debug';
+};
+/**
+ * All accepted forms of a Kubb configuration.
+ * Accepts `Config`/`Config[]`/promise or a factory (optionally receiving `TCliOptions`).
+ */
+type PossibleConfig<TCliOptions = undefined> = PossiblePromise<Config | Config[]> | ((...args: [TCliOptions] extends [undefined] ? [] : [TCliOptions]) => PossiblePromise<Config | Config[]>);
+/**
+ * Full output produced by a successful or failed build.
+ */
+type BuildOutput = {
   /**
-   * Tag name to match (case-sensitive). Can be a literal string or regex pattern.
+   * Plugins that threw during installation, paired with the caught error.
    */
-  pattern: string | RegExp;
-};
-type ByOperationId = {
+  failedPlugins: Set<{
+    plugin: Plugin;
+    error: Error;
+  }>;
+  files: Array<FileNode>;
+  driver: PluginDriver;
   /**
-   * Filter by OpenAPI `operationId` field. Each operation (GET, POST, etc.) has a unique identifier.
+   * Elapsed time in milliseconds for each plugin, keyed by plugin name.
    */
-  type: 'operationId';
+  pluginTimings: Map<string, number>;
+  error?: Error;
   /**
-   * Operation ID to match (case-sensitive). Can be a literal string or regex pattern.
+   * Read-only view of every file written during this build.
+   *
+   * Keys are limited to this run. Reads go straight to `config.storage`,
+   * so nothing extra is held in memory.
+   *
+   * @example Read a generated file
+   * ```ts
+   * const code = await buildOutput.storage.getItem('/src/gen/pet.ts')
+   * ```
+   *
+   * @example List all generated file paths
+   * ```ts
+   * const paths = await buildOutput.storage.getKeys()
+   * ```
    */
-  pattern: string | RegExp;
+  storage: Storage;
 };
-type ByPath = {
-  /**
-   * Filter by OpenAPI `path` (URL endpoint). Useful to group or filter by service segments like `/pets`, `/users`, etc.
-   */
-  type: 'path';
+/**
+ * Kubb code generation instance returned by {@link createKubb}.
+ *
+ * Use this when orchestrating multiple builds, inspecting plugin timings, or integrating Kubb into a larger toolchain.
+ * For a single one-off build, chain directly: `await createKubb(config).build()`.
+ */
+type Kubb$1 = {
   /**
-   * URL path to match (case-sensitive). Can be a literal string or regex pattern. Matches against the full path.
+   * Shared event emitter for lifecycle and status events. Attach listeners before calling `setup()` or `build()`.
    */
-  pattern: string | RegExp;
-};
-type ByMethod = {
+  readonly hooks: AsyncEventEmitter<KubbHooks>;
   /**
-   * Filter by HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'head'`, `'options'`.
+   * Read-only view of the files from the most recent `build()` or `safeBuild()` call.
+   * Only populated after the build completes.
+   *
+   * Keys are scoped to the current run. Reads go straight to `config.storage`,
+   * so nothing extra is held in memory.
+   *
+   * @example Read a generated file
+   * ```ts
+   * const { storage } = await kubb.safeBuild()
+   * const code = await storage.getItem('/src/gen/pet.ts')
+   * ```
+   *
+   * @example Walk every generated file
+   * ```ts
+   * for (const path of await kubb.storage.getKeys()) {
+   *   const code = await kubb.storage.getItem(path)
+   * }
+   * ```
    */
-  type: 'method';
+  readonly storage: Storage;
   /**
-   * HTTP method to match (case-insensitive when using string, or regex for dynamic matching).
+   * Plugin driver managing all plugins. Available after `setup()` completes.
    */
-  pattern: HttpMethod | RegExp;
-};
-type BySchemaName = {
+  readonly driver: PluginDriver;
   /**
-   * Filter by schema component name (TypeScript or JSON schema). Matches schemas in `#/components/schemas`.
+   * Resolved configuration with defaults applied. Available after `setup()` completes.
    */
-  type: 'schemaName';
+  readonly config: Config;
   /**
-   * Schema name to match (case-sensitive). Can be a literal string or regex pattern.
+   * Resolves config and initializes the driver. `build()` calls this automatically.
    */
-  pattern: string | RegExp;
-};
-type ByContentType = {
+  setup(): Promise<void>;
   /**
-   * Filter by response or request content type: `'application/json'`, `'application/xml'`, etc.
+   * Runs the full pipeline and throws on any plugin error. Automatically calls `setup()` if needed.
    */
-  type: 'contentType';
+  build(): Promise<BuildOutput>;
   /**
-   * Content type to match (case-sensitive). Can be a literal string or regex pattern.
+   * Runs the full pipeline and captures errors in `BuildOutput` instead of throwing. Automatically calls `setup()` if needed.
    */
-  pattern: string | RegExp;
+  safeBuild(): Promise<BuildOutput>;
 };
 /**
- * A pattern filter that prevents matching nodes from being generated.
- *
- * Use to skip code generation for specific operations or schemas. For example, exclude deprecated endpoints
- * or internal-only schemas. Can filter by tag, operationId, path, HTTP method, content type, or schema name.
- *
- * @example
- * ```ts
- * exclude: [
- *   { type: 'tag', pattern: 'internal' },          // skip "internal" tag
- *   { type: 'path', pattern: /^\/admin/ },          // skip all /admin endpoints
- *   { type: 'operationId', pattern: 'deprecated_*' }  // skip operationIds matching pattern
- * ]
- * ```
- */
-type Exclude$1 = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
-/**
- * A pattern filter that restricts generation to only matching nodes.
- *
- * Use to generate code for a subset of operations or schemas. For example, only generate for a specific service
- * tag or only for "production" endpoints. Can filter by tag, operationId, path, HTTP method, content type, or schema name.
- *
- * @example
- * ```ts
- * include: [
- *   { type: 'tag', pattern: 'public' },        // generate only "public" tag
- *   { type: 'path', pattern: /^\/api\/v1/ },   // generate only v1 endpoints
- * ]
- * ```
- */
-type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
-/**
- * A pattern filter paired with partial option overrides applied when the pattern matches.
- *
- * Use to customize generation for specific operations or schemas. For example, apply different output paths
- * for different tags, or use custom resolver functions per operation. Can filter by tag, operationId, path,
- * HTTP method, schema name, or content type.
- *
- * @example
- * ```ts
- * override: [
- *   {
- *     type: 'tag',
- *     pattern: 'admin',
- *     options: { output: { path: './src/gen/admin' } }  // admin APIs go to separate folder
- *   },
- *   {
- *     type: 'operationId',
- *     pattern: 'listPets',
- *     options: { exclude: true }  // skip this specific operation
- *   }
- * ]
- * ```
+ * Type guard to check if a given config has an `input.path`.
  */
-type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
-  options: Partial<TOptions>;
+declare function isInputPath(config: UserConfig | undefined): config is UserConfig<InputPath> & {
+  input: InputPath;
 };
-/**
- * File-specific parameters for `Resolver.resolvePath`.
- *
- * Pass alongside a `ResolverContext` to identify which file to resolve.
- * Provide `tag` for tag-based grouping or `path` for path-based grouping.
- *
- * @example
- * ```ts
- * resolver.resolvePath(
- *   { baseName: 'petTypes.ts', tag: 'pets' },
- *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
- * )
- * // → '/src/types/petsController/petTypes.ts'
- * ```
- */
-type ResolverPathParams = {
-  baseName: FileNode['baseName'];
-  pathMode?: 'single' | 'split';
-  /**
-   * Tag value used when `group.type === 'tag'`.
-   */
-  tag?: string;
-  /**
-   * Path value used when `group.type === 'path'`.
-   */
-  path?: string;
+declare function isInputPath(config: Config | undefined): config is Config<InputPath> & {
+  input: InputPath;
 };
-/**
- * Shared context passed as the second argument to `Resolver.resolvePath` and `Resolver.resolveFile`.
- *
- * Describes where on disk output is rooted, which output config is active, and the optional
- * grouping strategy that controls subdirectory layout.
- *
- * @example
- * ```ts
- * const context: ResolverContext = {
- *   root: config.root,
- *   output,
- *   group,
- * }
- * ```
- */
-type ResolverContext = {
-  root: string;
-  output: Output;
-  group?: Group;
-  /**
-   * Plugin name used to populate `meta.pluginName` on the resolved file.
-   */
-  pluginName?: string;
+type CreateKubbOptions = {
+  hooks?: AsyncEventEmitter<KubbHooks>;
 };
 /**
- * File-specific parameters for `Resolver.resolveFile`.
+ * Creates a Kubb instance bound to a single config entry.
  *
- * Pass alongside a `ResolverContext` to fully describe the file to resolve.
- * `tag` and `path` are used only when a matching `group` is present in the context.
+ * Accepts a user-facing config shape and resolves it to a full {@link Config} during
+ * `setup()`. The instance then holds shared state (`hooks`, `storage`, `driver`, `config`)
+ * across the `setup → build` lifecycle. Attach event listeners to `kubb.hooks` before
+ * calling `setup()` or `build()`.
  *
  * @example
  * ```ts
- * resolver.resolveFile(
- *   { name: 'listPets', extname: '.ts', tag: 'pets' },
- *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
- * )
- * // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
- * ```
- */
-type ResolverFileParams = {
-  name: string;
-  extname: FileNode['extname'];
-  /**
-   * Tag value used when `group.type === 'tag'`.
-   */
-  tag?: string;
-  /**
-   * Path value used when `group.type === 'path'`.
-   */
-  path?: string;
-};
-/**
- * Context passed to `Resolver.resolveBanner` and `Resolver.resolveFooter`.
+ * const kubb = createKubb(userConfig)
  *
- * `output` is optional — not every plugin configures a banner/footer.
- * `config` carries the global Kubb config, used to derive the default Kubb banner.
+ * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
+ *   console.log(`${plugin.name} completed in ${duration}ms`)
+ * })
  *
- * @example
- * ```ts
- * resolver.resolveBanner(inputNode, { output: { banner: '// generated' }, config })
- * // → '// generated'
+ * const { files, failedPlugins } = await kubb.safeBuild()
  * ```
  */
-type ResolveBannerContext = {
-  output?: Pick<Output, 'banner' | 'footer'>;
-  config: Config;
-};
-/**
- * CLI options derived from command-line flags.
- */
-type CLIOptions = {
-  /**
-   * Path to `kubb.config.js`.
-   */
-  config?: string;
-  /**
-   * Enable watch mode for input files.
-   */
-  watch?: boolean;
-  /**
-   * Logging verbosity for CLI usage.
-   * @default 'silent'
-   */
-  logLevel?: 'silent' | 'info' | 'debug';
-};
-/**
- * All accepted forms of a Kubb configuration.
- *
- * Config is always `@kubb/core` {@link Config}.
- * - `PossibleConfig` accepts `Config`/`Config[]`/promise or a no-arg config factory.
- * - `PossibleConfig<TCliOptions>` accepts the same config forms or a config factory receiving `TCliOptions`.
- */
-type PossibleConfig<TCliOptions = undefined> = PossiblePromise<Config | Config[]> | ((...args: [TCliOptions] extends [undefined] ? [] : [TCliOptions]) => PossiblePromise<Config | Config[]>);
+declare function createKubb(userConfig: UserConfig, options?: CreateKubbOptions): Kubb$1;
 //#endregion
-export { defineParser as $, KubbPluginStartContext as A, Override as B, KubbGenerationSummaryContext as C, KubbLifecycleStartContext as D, KubbInfoContext as E, Logger as F, ResolveOptionsContext as G, PossibleConfig as H, LoggerContext as I, ResolverFileParams as J, Resolver as K, LoggerOptions as L, KubbSuccessContext as M, KubbVersionNewContext as N, KubbPluginEndContext as O, KubbWarnContext as P, Parser as Q, NormalizedPlugin as R, KubbGenerationStartContext as S, KubbHookStartContext as T, ResolveBannerContext as U, PluginFactoryOptions as V, ResolveNameParams as W, UserConfig as X, ResolverPathParams as Y, UserLogger as Z, KubbErrorContext as _, logLevel as _t, Config as a, createKubb as at, KubbFilesProcessingStartContext as b, GeneratorContext as c, Plugin as ct, InputData as d, defineGenerator as dt, Middleware as et, InputPath as f, Storage as ft, KubbDebugContext as g, createRenderer as gt, KubbConfigEndContext as h, RendererFactory as ht, CLIOptions as i, BuildOutput as it, KubbPluginsEndContext as j, KubbPluginSetupContext as k, Group as l, definePlugin as lt, KubbBuildStartContext as m, Renderer as mt, AdapterFactoryOptions as n, Kubb$1 as nt, DevtoolsOptions as o, PluginDriver as ot, KubbBuildEndContext as p, createStorage as pt, ResolverContext as q, AdapterSource as r, KubbHooks as rt, Exclude$1 as s, FileManager as st, Adapter as t, defineMiddleware as tt, Include as u, Generator as ut, KubbFileProcessingUpdateContext as v, AsyncEventEmitter as vt, KubbHookEndContext as w, KubbGenerationEndContext as x, KubbFilesProcessingEndContext as y, Output as z };
-//# sourceMappingURL=types-CuNocrbJ.d.ts.map
+export { ResolverPathParams as $, isInputPath as A, KubbPluginSetupContext as B, KubbPluginsEndContext as C, AsyncEventEmitter as Ct, PossibleConfig as D, KubbWarnContext as E, FileManager as F, Plugin as G, NormalizedPlugin as H, Exclude as I, ResolveBannerContext as J, PluginFactoryOptions as K, Group as L, GeneratorContext as M, defineGenerator as N, UserConfig as O, PluginDriver as P, ResolverFileParams as Q, Include as R, KubbLifecycleStartContext as S, logLevel as St, KubbVersionNewContext as T, Output as U, KubbPluginStartContext as V, Override as W, Resolver as X, ResolveOptionsContext as Y, ResolverContext as Z, KubbGenerationSummaryContext as _, createRenderer as _t, InputPath as a, LoggerOptions as at, KubbHooks as b, AdapterSource as bt, KubbBuildStartContext as c, FileProcessor as ct, KubbErrorContext as d, defineParser as dt, defineResolver as et, KubbFileProcessingUpdateContext as f, DevtoolsOptions as ft, KubbGenerationStartContext as g, RendererFactory as gt, KubbGenerationEndContext as h, Renderer as ht, InputData as i, LoggerContext as it, Generator as j, createKubb as k, KubbConfigEndContext as l, FileProcessorEvents as lt, KubbFilesProcessingStartContext as m, createStorage as mt, CLIOptions as n, defineMiddleware as nt, Kubb$1 as o, UserLogger as ot, KubbFilesProcessingEndContext as p, Storage as pt, definePlugin as q, Config as r, Logger as rt, KubbBuildEndContext as s, defineLogger as st, BuildOutput as t, Middleware as tt, KubbDebugContext as u, Parser as ut, KubbHookEndContext as v, Adapter as vt, KubbSuccessContext as w, KubbInfoContext as x, createAdapter as xt, KubbHookStartContext as y, AdapterFactoryOptions as yt, KubbPluginEndContext as z };
+//# sourceMappingURL=createKubb-BSfMDBwR.d.ts.map