@kubb/core 5.0.0-beta.3 → 5.0.0-beta.31

package/dist/{types-CC09VtBt.d.ts → createKubb-6zii1jo-.d.ts}

@@ -1,5 +1,5 @@
 import { t as __name } from "./chunk--u3MIqq1.js";
-import { FileNode, HttpMethod, ImportNode, InputNode, Node, OperationNode, SchemaNode, UserFileNode, Visitor } from "@kubb/ast";
+import { FileNode, HttpMethod, ImportNode, InputMeta, InputNode, InputStreamNode, Node, OperationNode, SchemaNode, UserFileNode, Visitor } from "@kubb/ast";
 
 //#region ../../internals/utils/src/asyncEventEmitter.d.ts
 /**
@@ -33,7 +33,7 @@ declare class AsyncEventEmitter<TEvents extends { [K in keyof TEvents]: unknown[
    * await emitter.emit('build', 'petstore')
    * ```
    */
-  emit<TEventName extends keyof TEvents & string>(eventName: TEventName, ...eventArgs: TEvents[TEventName]): Promise<void>;
+  emit<TEventName extends keyof TEvents & string>(eventName: TEventName, ...eventArgs: TEvents[TEventName]): Promise<void> | void;
   /**
    * Registers a persistent listener for `eventName`.
    *
@@ -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,314 +113,1183 @@ declare const logLevel: {
   readonly debug: 5;
 };
 //#endregion
+//#region src/createAdapter.d.ts
+/**
+ * Source data handed to an adapter's `parse` function. Mirrors the config
+ * input shape with paths resolved to absolute.
+ *
+ * - `{ type: 'path' }`: single file on disk.
+ * - `{ type: 'paths' }`: multiple files (e.g. split spec).
+ * - `{ type: 'data' }`: raw string or parsed object provided inline.
+ */
+type AdapterSource = {
+  type: 'path';
+  path: string;
+} | {
+  type: 'data';
+  data: string | unknown;
+} | {
+  type: 'paths';
+  paths: Array<string>;
+};
+/**
+ * Generic parameters used by `createAdapter` and the resulting `Adapter` type.
+ *
+ * - `TName`: unique adapter identifier (`'oas'`, `'asyncapi'`, ...).
+ * - `TOptions`: user-facing options accepted by the adapter factory.
+ * - `TResolvedOptions`: options after defaults are 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;
+};
+/**
+ * Converts input files or inline data into Kubb's universal AST `InputNode`.
+ *
+ * Adapters live between the spec format and the plugins. The built-in
+ * `@kubb/adapter-oas` handles OpenAPI 2.0, 3.0, and 3.1; custom adapters can
+ * support GraphQL, gRPC, AsyncAPI, or any domain-specific schema language.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb'
+ * import { adapterOas } from '@kubb/adapter-oas'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   adapter: adapterOas(),
+ *   plugins: [pluginTs()],
+ * })
+ * ```
+ */
+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;
+  /**
+   * 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>;
+  /**
+   * Memory-efficient streaming variant of `parse()`.
+   *
+   * Returns an `InputStreamNode` whose `schemas` and `operations` are `AsyncIterable`.
+   * Each `for await` loop creates a fresh parse pass over the cached in-memory document.
+   * No pre-built arrays are held in memory.
+   */
+  stream?: (source: AdapterSource) => Promise<InputStreamNode>;
+};
+type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>;
+/**
+ * Defines a custom adapter that translates a spec format into Kubb's universal
+ * AST. Use this when you need to consume GraphQL, gRPC, AsyncAPI, or another
+ * domain-specific schema. Built-in adapters: `@kubb/adapter-oas` for
+ * OpenAPI/Swagger documents.
+ *
+ * Adapters must return an `InputNode` from `parse`. That node is what every
+ * plugin in the build consumes.
+ *
+ * @example
+ * ```ts
+ * import { createAdapter, ast, type AdapterFactoryOptions } from '@kubb/core'
+ *
+ * type MyAdapter = AdapterFactoryOptions<'my-adapter', { validate?: boolean }>
+ *
+ * export const myAdapter = createAdapter<MyAdapter>((options) => ({
+ *   name: 'my-adapter',
+ *   options,
+ *   document: null,
+ *   async parse(_source) {
+ *     // Convert `source` (path or inline data) into an InputNode.
+ *     return ast.createInput()
+ *   },
+ *   getImports: () => [],
+ *   async validate() {
+ *     // Throw or call ctx.error here when the spec is invalid.
+ *   },
+ * }))
+ * ```
+ */
+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.
  *
- * The generic `TElement` is the type of the element the renderer accepts —
- * e.g. `KubbReactElement` for `@kubb/renderer-jsx`, or a custom type for
- * your own renderer.  Defaults to `unknown` so that generators which do not
- * care about the element type continue to work without specifying it.
- *
- * This allows core to drive rendering without a hard dependency on
- * `@kubb/renderer-jsx` or any specific renderer implementation.
+ * `TElement` is the type the renderer accepts, for example `KubbReactElement`
+ * for `@kubb/renderer-jsx` or a custom type for your own renderer. Defaults to
+ * `unknown` so generators that don't care about the element type work without
+ * specifying it.
  */
 type Renderer<TElement = unknown> = {
+  /**
+   * Renders `element` and populates {@link files} with the resulting {@link FileNode} objects.
+   * Called once per render cycle; must resolve before {@link files} is read.
+   */
   render(element: TElement): Promise<void>;
+  /**
+   * Tears down the renderer and releases any held resources.
+   * Pass an `Error` to signal a failure, a number for an exit code, or omit for a clean shutdown.
+   */
   unmount(error?: Error | number | null): void;
+  /**
+   * Releases any held resources. `[Symbol.dispose]` delegates here.
+   */
+  dispose(): void;
+  /**
+   * Accumulated {@link FileNode} results produced by the last {@link render} call.
+   * Not populated when {@link stream} is implemented.
+   */
   readonly files: Array<FileNode>;
+  /**
+   * When present, core calls this instead of {@link render} and {@link files},
+   * forwarding each file to `FileManager` as soon as it is ready.
+   */
+  stream?(element: TElement): Iterable<FileNode>;
+  /**
+   * Disposer hook so renderers participate in `using` blocks: `using r = rendererFactory()`
+   * guarantees {@link dispose} runs on every exit path, including thrown errors.
+   */
+  [Symbol.dispose](): void;
 };
 /**
- * A factory function that produces a fresh {@link Renderer} per render.
+ * A factory function that produces a fresh {@link Renderer} per render cycle.
  *
  * Generators use this to declare which renderer handles their output.
  */
 type RendererFactory<TElement = unknown> = () => Renderer<TElement>;
 /**
- * Creates a renderer factory for use in generator definitions.
+ * Defines a renderer factory. Renderers turn the generator's return value
+ * (JSX, a template string, a tree of any shape) into `FileNode`s that get
+ * written to disk.
  *
- * Wrap your renderer factory function with this helper to register it as the
- * renderer for a generator. Core will call this factory once per render cycle
- * to obtain a fresh renderer instance.
+ * Use this to support output formats beyond JSX — for instance, a Handlebars
+ * renderer, a string-template renderer, or a renderer that writes binary
+ * files. Plugins and generators pick the renderer to use via the `renderer`
+ * field on `defineGenerator`.
  *
- * @example
+ * @example A minimal renderer that wraps a custom runtime
  * ```ts
- * // packages/renderer-jsx/src/index.ts
- * export const jsxRenderer = createRenderer(() => {
- *   const runtime = new Runtime()
+ * import { createRenderer } from '@kubb/core'
+ *
+ * export const myRenderer = createRenderer(() => {
+ *   const runtime = new MyRuntime()
  *   return {
- *     async render(element) { await runtime.render(element) },
- *     get files() { return runtime.nodes },
- *     unmount(error) { runtime.unmount(error) },
+ *     async render(element) {
+ *       await runtime.render(element)
+ *     },
+ *     get files() {
+ *       return runtime.files
+ *     },
+ *     dispose() {
+ *       runtime.dispose()
+ *     },
+ *     unmount(error) {
+ *       runtime.dispose(error)
+ *     },
+ *     [Symbol.dispose]() {
+ *       this.dispose()
+ *     },
  *   }
  * })
- *
- * // packages/plugin-zod/src/generators/zodGenerator.tsx
- * import { jsxRenderer } from '@kubb/renderer-jsx'
- * export const zodGenerator = defineGenerator<PluginZod>({
- *   name: 'zod',
- *   renderer: jsxRenderer,
- *   schema(node, options) { return <File ...>...</File> },
- * })
  * ```
  */
 declare function createRenderer<TElement = unknown>(factory: RendererFactory<TElement>): RendererFactory<TElement>;
 //#endregion
 //#region src/createStorage.d.ts
+/**
+ * Backend that persists generated files. Kubb ships with `fsStorage` (writes
+ * to disk) and `memoryStorage` (keeps everything in RAM). Implement this
+ * interface to write to S3, a database, or any other target.
+ */
 type Storage = {
   /**
-   * Identifier used for logging and debugging (e.g. `'fs'`, `'s3'`).
+   * Identifier used in logs and diagnostics (`'fs'`, `'memory'`, `'s3'`).
    */
   readonly name: string;
   /**
-   * Returns `true` when an entry for `key` exists in storage.
+   * Returns `true` when an entry for `key` exists.
    */
   hasItem(key: string): Promise<boolean>;
   /**
-   * Returns the stored string value, or `null` when `key` does not exist.
+   * Reads the stored string. Returns `null` when the key is missing.
    */
   getItem(key: string): Promise<string | null>;
   /**
-   * Persists `value` under `key`, creating any required structure.
+   * Stores `value` under `key`, creating any required structure (directories,
+   * buckets, ...).
    */
   setItem(key: string, value: string): Promise<void>;
   /**
-   *  Removes the entry for `key`. No-ops when the key does not exist.
+   * Deletes the entry for `key`. No-op when the key does not exist.
    */
   removeItem(key: string): Promise<void>;
   /**
-   * Returns all keys, optionally filtered to those starting with `base`.
+   * Returns every key. Pass `base` to filter to keys starting with that prefix.
    */
   getKeys(base?: string): Promise<Array<string>>;
   /**
-   * Removes all entries, optionally scoped to those starting with `base`.
+   * Removes every entry. Pass `base` to scope the wipe to a key prefix.
    */
   clear(base?: string): Promise<void>;
   /**
-   * Optional teardown hook called after the build completes.
+   * Optional teardown hook called after the build completes. Use to flush
+   * buffers, close connections, or release file locks.
    */
   dispose?(): Promise<void>;
 };
 /**
- * Factory for implementing custom storage backends that control where generated files are written.
- *
- * Takes a builder function `(options: TOptions) => Storage` and returns a factory `(options?: TOptions) => Storage`.
- * Kubb provides filesystem and in-memory implementations out of the box.
+ * Defines a custom storage backend. The builder receives user options and
+ * returns a `Storage` implementation. Kubb ships with filesystem and
+ * in-memory storages — reach for this when you need to write generated files
+ * elsewhere (cloud storage, a database, a remote API).
  *
- * @note Call the returned factory with optional options to instantiate the storage adapter.
- *
- * @example
+ * @example In-memory storage (the built-in implementation)
  * ```ts
  * import { createStorage } from '@kubb/core'
  *
  * export const memoryStorage = createStorage(() => {
  *   const store = new Map<string, string>()
+ *
  *   return {
  *     name: 'memory',
- *     async hasItem(key) { return store.has(key) },
- *     async getItem(key) { return store.get(key) ?? null },
- *     async setItem(key, value) { store.set(key, value) },
- *     async removeItem(key) { store.delete(key) },
+ *     async hasItem(key) {
+ *       return store.has(key)
+ *     },
+ *     async getItem(key) {
+ *       return store.get(key) ?? null
+ *     },
+ *     async setItem(key, value) {
+ *       store.set(key, value)
+ *     },
+ *     async removeItem(key) {
+ *       store.delete(key)
+ *     },
  *     async getKeys(base) {
  *       const keys = [...store.keys()]
  *       return base ? keys.filter((k) => k.startsWith(base)) : keys
  *     },
- *     async clear(base) { if (!base) store.clear() },
+ *     async clear(base) {
+ *       if (!base) store.clear()
+ *     },
  *   }
  * })
- *
- * // Instantiate:
- * const storage = memoryStorage()
  * ```
  */
 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'];
+};
 /**
- * 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>
- *   },
- * })
- * ```
+ * Converts a resolved {@link FileNode} into the final source string that gets
+ * written to disk. Kubb ships with TypeScript and TSX parsers; add your own
+ * for new file types (JSON, Markdown, ...).
  */
-type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown> = {
+type Parser<TMeta extends object = any, TNode = unknown> = {
   /**
-   * Used in diagnostic messages and debug output.
+   * Display name used in diagnostics and the parser registry.
    */
   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).
+   * File extensions this parser handles. Set to `undefined` to define a
+   * catch-all fallback used when no other parser claims the extension.
    *
    * @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).
+   * `['.ts', '.js']`
    */
-  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>;
+  extNames: Array<FileNode['extname']> | undefined;
   /**
-   * 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).
+   * Serialise the file's AST into source code.
    */
-  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>;
+  parse(file: FileNode<TMeta>, options?: PrintOptions): string;
   /**
-   * 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.
+   * Render compiler AST nodes for this parser's language into source text.
+   * Plugins call this to format the nodes they assemble before handing them
+   * back to the parser as `FileNode.sources`.
    */
-  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>;
+  print(...nodes: Array<TNode>): string;
 };
 /**
- * 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.
+ * Defines a parser with type-safe `this`. Used to register handlers for new
+ * file extensions or to plug a non-TypeScript output into the build.
+ *
+ * @example
+ * ```ts
+ * import { defineParser, ast } from '@kubb/core'
+ *
+ * export const jsonParser = defineParser({
+ *   name: 'json',
+ *   extNames: ['.json'],
+ *   parse(file) {
+ *     return file.sources
+ *       .map((source) => ast.extractStringsFromNodes(source.nodes ?? []))
+ *       .join('\n')
+ *   },
+ *   print(...nodes) {
+ *     return nodes.map(String).join('\n')
+ *   },
+ * })
+ * ```
  */
-declare function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(generator: Generator<TOptions, TElement>): Generator<TOptions, TElement>;
+declare function defineParser<T extends Parser>(parser: T): T;
 //#endregion
-//#region src/definePlugin.d.ts
+//#region src/FileProcessor.d.ts
+type ParseOptions = {
+  parsers?: Map<FileNode['extname'], Parser>;
+  extension?: Record<FileNode['extname'], FileNode['extname'] | ''>;
+};
+type FileProcessorEvents = {
+  start: [files: Array<FileNode>];
+  update: [params: {
+    file: FileNode;
+    source?: string;
+    processed: number;
+    total: number;
+    percentage: number;
+  }];
+  end: [files: Array<FileNode>];
+};
+type ParsedFile = {
+  file: FileNode;
+  source: string;
+  processed: number;
+  total: number;
+  percentage: number;
+};
 /**
- * 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> = {
-  /**
-   * Unique name for the plugin, following the same naming convention as `createPlugin`.
-   */
-  name: string;
+declare class FileProcessor {
+  readonly events: AsyncEventEmitter<FileProcessorEvents>;
+  parse(file: FileNode, {
+    parsers,
+    extension
+  }?: ParseOptions): string;
+  stream(files: ReadonlyArray<FileNode>, options?: ParseOptions): Generator<ParsedFile>;
+  run(files: Array<FileNode>, options?: ParseOptions): Promise<Array<FileNode>>;
   /**
-   * Plugins that must be registered before this plugin executes.
-   * An error is thrown at startup when any listed dependency is missing.
+   * Clears all registered event listeners.
    */
-  dependencies?: Array<string>;
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
+//#endregion
+//#region src/defineLogger.d.ts
+/**
+ * Options accepted by a logger's `install` callback.
+ */
+type LoggerOptions = {
   /**
-   * 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`.
+   * Output verbosity. Use the `logLevel` constants exported from `@kubb/core`
+   * (`silent`, `error`, `warn`, `info`, `verbose`, `debug`).
    */
-  enforce?: 'pre' | 'post';
+  logLevel: (typeof logLevel)[keyof typeof logLevel];
+};
+/**
+ * Event emitter handed to `Logger.install`. Use `.on('kubb:info', ...)` and
+ * friends to subscribe to build events.
+ */
+type LoggerContext = AsyncEventEmitter<KubbHooks>;
+/**
+ * Logger contract. A logger receives the build's event emitter and subscribes
+ * to whichever lifecycle events it wants to forward to its destination
+ * (console, file, remote sink).
+ */
+type Logger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = {
   /**
-   * The options passed by the user when calling the plugin factory.
+   * Display name used in diagnostics.
    */
-  options?: TFactory['options'];
+  name: string;
   /**
-   * Lifecycle event handlers for this plugin.
-   * Any event from the global `KubbHooks` map can be subscribed to here.
+   * Called once per build with the shared event emitter. Subscribe to events
+   * here. The return value (if any) is forwarded to whoever installed the
+   * logger, which is handy for sink factories.
    */
-  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`.
+ * Defines a typed logger. Use the second type parameter to declare a return
+ * value from `install`, which is handy when the logger exposes a sink factory
+ * or cleanup callback to the caller.
  *
- * Handlers live in a single `hooks` object (inspired by Astro integrations).
- * All lifecycle events from `KubbHooks` are available for subscription.
+ * @example Basic logger
+ * ```ts
+ * import { defineLogger } from '@kubb/core'
  *
- * @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`).
+ * export const myLogger = defineLogger({
+ *   name: 'my-logger',
+ *   install(context) {
+ *     context.on('kubb:info', ({ message }) => console.log('ℹ', message))
+ *     context.on('kubb:error', ({ error }) => console.error('✗', error.message))
+ *   },
+ * })
+ * ```
  *
- * @example
+ * @example Logger that returns a hook sink factory
  * ```ts
- * import { definePlugin } from '@kubb/core'
- *
- * export const pluginTs = definePlugin((options: { prefix?: string } = {}) => ({
- *   name: 'plugin-ts',
- *   hooks: {
- *     'kubb:plugin:setup'(ctx) {
- *       ctx.setResolver(resolverTs)
- *     },
+ * import { defineLogger, type LoggerOptions } from '@kubb/core'
+ * import type { HookSinkFactory } from './sinks'
+ *
+ * export const myLogger = defineLogger<LoggerOptions, HookSinkFactory>({
+ *   name: 'my-logger',
+ *   install(context) {
+ *     // … register event handlers …
+ *     return () => ({ onStdout: console.log })
  *   },
- * }))
+ * })
  * ```
  */
-declare function definePlugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>(factory: (options: TFactory['options']) => Plugin<TFactory>): (options?: TFactory['options']) => Plugin<TFactory>;
+declare function defineLogger<Options extends LoggerOptions = LoggerOptions, TInstallReturn = void>(logger: UserLogger<Options, TInstallReturn>): Logger<Options, TInstallReturn>;
 //#endregion
-//#region src/FileManager.d.ts
+//#region src/defineMiddleware.d.ts
+/**
+ * A middleware instance. Subscribes to lifecycle events via `hooks`. Middleware
+ * handlers always fire after every plugin handler for the same event, so they
+ * see the full set of generated files.
+ */
+type Middleware = {
+  /**
+   * Unique name. Use a `middleware-<feature>` convention (e.g.
+   * `middleware-barrel`).
+   */
+  name: string;
+  /**
+   * Lifecycle event handlers. Any event from the global `KubbHooks` map can be
+   * subscribed to here. Handlers run after all plugin handlers for that event.
+   */
+  hooks: { [K in keyof KubbHooks]?: (...args: KubbHooks[K]) => void | Promise<void> };
+};
+/**
+ * Creates a middleware factory. Middleware fires after every plugin handler
+ * for the same event, which makes it the natural place for post-processing
+ * (barrel files, lint runs, audit logs).
+ *
+ * Per-build state belongs inside the factory closure so each `createKubb`
+ * invocation gets its own isolated instance.
+ *
+ * @example Stateless middleware
+ * ```ts
+ * import { defineMiddleware } from '@kubb/core'
+ *
+ * export const logMiddleware = defineMiddleware(() => ({
+ *   name: 'log-middleware',
+ *   hooks: {
+ *     'kubb:build:end'({ files }) {
+ *       console.log(`Build complete with ${files.length} files`)
+ *     },
+ *   },
+ * }))
+ * ```
+ *
+ * @example Middleware with options and per-build state
+ * ```ts
+ * import { defineMiddleware } from '@kubb/core'
+ *
+ * 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 defineMiddleware<TOptions extends object = object>(factory: (options: TOptions) => Middleware): (options?: TOptions) => Middleware;
+//#endregion
+//#region src/defineResolver.d.ts
+/**
+ * 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: 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(meta: InputMeta | undefined, context: ResolveBannerContext): string | null;
+  resolveFooter(meta: InputMeta | undefined, context: ResolveBannerContext): string | null;
+};
+/**
+ * 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;
+};
+/**
+ * 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;
+};
+/**
+ * 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'];
+  /**
+   * Tag value used when `group.type === 'tag'`.
+   */
+  tag?: string;
+  /**
+   * Path value used when `group.type === 'path'`.
+   */
+  path?: string;
+};
+/**
+ * Per-file context describing the file a banner/footer is being resolved for.
+ *
+ * Supplied by the generator (or the barrel middleware) at resolve-time and merged
+ * into `BannerMeta` so a `banner`/`footer` function can branch on the file kind —
+ * e.g. omit a `'use server'` directive on re-export files.
+ */
+type ResolveBannerFile = {
+  /**
+   * Full output path of the file being generated.
+   */
+  path: string;
+  /**
+   * File name only, e.g. `'stocks.ts'`.
+   */
+  baseName: string;
+  /**
+   * `true` for `index.ts` re-export barrels.
+   */
+  isBarrel?: boolean;
+  /**
+   * `true` for group `[dir]/[dir].ts` aggregation files.
+   */
+  isAggregation?: boolean;
+};
+/**
+ * Document metadata extended with per-file context, passed to a `banner`/`footer` function.
+ *
+ * Carries everything in {@link InputMeta} plus the file the banner is rendered into, so a
+ * single function can decide per file (e.g. skip a directive on barrel/aggregation files).
+ *
+ * @example Skip a directive on re-export files
+ * `banner: (meta) => (meta.isBarrel || meta.isAggregation) ? '' : "'use server'"`
+ */
+type BannerMeta = InputMeta & {
+  /**
+   * Full output path of the file being generated.
+   */
+  filePath: string;
+  /**
+   * File name only, e.g. `'stocks.ts'`.
+   */
+  baseName: string;
+  /**
+   * `true` for `index.ts` re-export barrels.
+   */
+  isBarrel: boolean;
+  /**
+   * `true` for group `[dir]/[dir].ts` aggregation files.
+   */
+  isAggregation: boolean;
+};
+/**
+ * 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.
+ * `file` carries per-file context forwarded to a `banner`/`footer` function.
+ *
+ * @example
+ * ```ts
+ * resolver.resolveBanner(meta, { output: { banner: '// generated' }, config })
+ * // → '// generated'
+ * ```
+ */
+type ResolveBannerContext = {
+  output?: Pick<Output, 'banner' | 'footer'>;
+  config: Config;
+  file?: ResolveBannerFile;
+};
+/**
+ * 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']>;
+/**
+ * Defines a plugin resolver. The resolver is the object that decides what
+ * every generated symbol and file path is called. Built-in defaults handle
+ * name casing, include/exclude/override filtering, output path computation,
+ * and file construction. Supply your own to override any of them:
+ *
+ * - `default` — name casing strategy (camelCase / PascalCase).
+ * - `resolveOptions` — include/exclude/override filtering.
+ * - `resolvePath` — output path computation.
+ * - `resolveFile` — full `FileNode` construction.
+ * - `resolveBanner` / `resolveFooter` — top/bottom-of-file text.
+ *
+ * Methods in the returned object can call sibling resolver methods via `this`,
+ * which keeps custom rules small (`this.default(name, 'type')` to delegate).
+ *
+ * @example Basic resolver with naming helpers
+ * ```ts
+ * export const resolverTs = defineResolver<PluginTs>(() => ({
+ *   name: 'default',
+ *   resolveName(name) {
+ *     return this.default(name, 'function')
+ *   },
+ *   resolveTypeName(name) {
+ *     return this.default(name, 'type')
+ *   },
+ * }))
+ * ```
+ *
+ * @example Custom output path
+ * ```ts
+ * import path from 'node:path'
+ *
+ * export const resolverTs = defineResolver<PluginTs>(() => ({
+ *   name: 'custom',
+ *   resolvePath({ baseName }, { root, output }) {
+ *     return path.resolve(root, output.path, 'generated', baseName)
+ *   },
+ * }))
+ * ```
+ */
+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 shared by every plugin. Each plugin extends this with
+ * its own keys via the `Kubb.PluginOptionsRegistry.output` interface merge.
+ */
+type Output<_TOptions = unknown> = {
+  /**
+   * Folder (or single file) where the plugin writes its generated code.
+   * Resolved against the global `output.path` set on `defineConfig`.
+   */
+  path: string;
+  /**
+   * Text prepended to every generated file. Useful for license headers,
+   * lint disables, or `@ts-nocheck` directives.
+   *
+   * A string is applied to every file (including barrel and aggregation re-export files).
+   * Pass a function to compute the banner from the file's `BannerMeta` — document metadata
+   * plus per-file context (`isBarrel`, `isAggregation`, `filePath`, `baseName`) — so you can
+   * skip the banner on specific files.
+   *
+   * @example Add a directive to source files but not re-export files
+   * `banner: (meta) => (meta.isBarrel || meta.isAggregation) ? '' : "'use server'"`
+   */
+  banner?: string | ((meta: BannerMeta) => string);
+  /**
+   * Text appended at the end of every generated file. Mirror of `banner`.
+   * Pass a function to compute the footer from the file's `BannerMeta`.
+   */
+  footer?: string | ((meta: BannerMeta) => string);
+  /**
+   * Allows the plugin to overwrite hand-written files at the same path.
+   * Defaults to `false` to protect manual edits.
+   *
+   * @default false
+   */
+  override?: boolean;
+} & ExtractRegistryKey$1<Kubb.PluginOptionsRegistry, 'output'>;
+/**
+ * Groups generated files into subdirectories based on an OpenAPI tag or path
+ * segment.
+ */
+type Group = {
+  /**
+   * Property used to assign each operation to a group.
+   * - `'tag'` — uses the first tag (`operation.getTags().at(0)?.name`).
+   * - `'path'` — uses the first segment of the operation's URL.
+   */
+  type: 'tag' | 'path';
+  /**
+   * Returns the subdirectory name from the group key. Defaults to
+   * `${camelCase(group)}Controller` for tags, or the first path segment.
+   */
+  name?: (context: {
+    group: string;
+  }) => string;
+};
+type ByTag = {
+  /**
+   * Filter by OpenAPI `tags` field. Matches one or more tags assigned to operations.
+   */
+  type: 'tag';
+  /**
+   * Tag name to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp;
+};
+type ByOperationId = {
+  /**
+   * Filter by OpenAPI `operationId` field. Each operation (GET, POST, etc.) has a unique identifier.
+   */
+  type: 'operationId';
+  /**
+   * Operation ID to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp;
+};
+type ByPath = {
+  /**
+   * Filter by OpenAPI `path` (URL endpoint). Useful to group or filter by service segments like `/pets`, `/users`, etc.
+   */
+  type: 'path';
+  /**
+   * URL path to match (case-sensitive). Can be a literal string or regex pattern. Matches against the full path.
+   */
+  pattern: string | RegExp;
+};
+type ByMethod = {
+  /**
+   * Filter by HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'head'`, `'options'`.
+   */
+  type: 'method';
+  /**
+   * HTTP method to match (case-insensitive when using string, or regex for dynamic matching).
+   */
+  pattern: HttpMethod | RegExp;
+};
+type BySchemaName = {
+  /**
+   * Filter by schema component name (TypeScript or JSON schema). Matches schemas in `#/components/schemas`.
+   */
+  type: 'schemaName';
+  /**
+   * Schema name to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp;
+};
+type ByContentType = {
+  /**
+   * Filter by response or request content type: `'application/json'`, `'application/xml'`, etc.
+   */
+  type: 'contentType';
+  /**
+   * Content type to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp;
+};
+/**
+ * Filter that skips matching operations or schemas during generation. Use it
+ * to drop deprecated endpoints, internal-only schemas, or anything you do
+ * not want code generated for.
+ *
+ * @example
+ * ```ts
+ * exclude: [
+ *   { type: 'tag', pattern: 'internal' },
+ *   { type: 'path', pattern: /^\/admin/ },
+ *   { type: 'operationId', pattern: /^deprecated_/ },
+ * ]
+ * ```
+ */
+type Exclude = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
+/**
+ * Filter that restricts generation to operations or schemas matching at least
+ * one entry. Useful for partial builds (one tag, one API version).
+ *
+ * @example
+ * ```ts
+ * include: [
+ *   { type: 'tag', pattern: 'public' },
+ *   { type: 'path', pattern: /^\/api\/v1/ },
+ * ]
+ * ```
+ */
+type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
+/**
+ * Filter paired with a partial options object. When the filter matches, the
+ * options are merged on top of the plugin defaults for that operation only.
+ * Useful for "this one tag goes to a different folder" rules.
+ *
+ * Entries are evaluated top to bottom; the first matching entry wins.
+ *
+ * @example
+ * ```ts
+ * override: [
+ *   {
+ *     type: 'tag',
+ *     pattern: 'admin',
+ *     options: { output: { path: './src/gen/admin' } },
+ *   },
+ *   {
+ *     type: 'operationId',
+ *     pattern: 'listPets',
+ *     options: { enumType: 'literal' },
+ *   },
+ * ]
+ * ```
+ */
+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> = {
+  /**
+   * 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$1<TFactory, TElement>): void;
+  /**
+   * Set or override the resolver for this plugin.
+   * The resolver controls file naming and path resolution.
+   */
+  setResolver(resolver: Partial<TFactory['resolver']>): void;
+  /**
+   * Set the AST transformer to pre-process nodes before they reach generators.
+   */
+  setTransformer(visitor: Visitor): void;
+  /**
+   * Set the renderer factory to process JSX elements from generators.
+   */
+  setRenderer(renderer: RendererFactory): void;
+  /**
+   * Set resolved options merged into the normalized plugin's `options`.
+   * Call this in `kubb:plugin:setup` to provide options generators need.
+   */
+  setOptions(options: TFactory['resolvedOptions']): void;
+  /**
+   * Inject a raw file into the build output, bypassing the generation pipeline.
+   */
+  injectFile(userFileNode: UserFileNode): void;
+  /**
+   * Merge a partial config update into the current build configuration.
+   */
+  updateConfig(config: Partial<Config>): void;
+  /**
+   * The resolved build configuration at setup time.
+   */
+  config: Config;
+  /**
+   * The plugin's user-provided options.
+   */
+  options: TFactory['options'];
+};
+/**
+ * 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 Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /**
+   * Unique name for the plugin, following the same naming convention as `createPlugin`.
+   */
+  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 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>;
+  };
+};
+/**
+ * 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>;
+    override: Array<Override<TOptions['resolvedOptions']>>;
+  };
+  resolver: TOptions['resolver'];
+  transformer?: Visitor;
+  renderer?: RendererFactory;
+  generators?: Array<Generator$1>;
+  apply?: (config: Config) => boolean;
+  version?: string;
+};
+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;
+};
 /**
- * In-memory file store for generated files.
+ * Wraps a plugin factory and returns a function that accepts user options and
+ * yields a fully typed `Plugin`. Lifecycle handlers go inside a single
+ * `hooks` object (inspired by Astro integrations).
  *
- * 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).
+ * Pass a `PluginFactoryOptions` type parameter to get a typed `ctx` inside
+ * `kubb:plugin:setup`. Plugin names should follow the `plugin-<feature>`
+ * convention (`plugin-react-query`, `plugin-zod`, ...).
  *
  * @example
  * ```ts
- * import { FileManager } from '@kubb/core'
+ * import { definePlugin } from '@kubb/core'
  *
+ * export const pluginTs = definePlugin((options: { prefix?: string } = {}) => ({
+ *   name: 'plugin-ts',
+ *   hooks: {
+ *     'kubb:plugin:setup'(ctx) {
+ *       ctx.setResolver(resolverTs)
+ *     },
+ *   },
+ * }))
+ * ```
+ */
+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 sharing a `path` are merged
+ * (sources/imports/exports concatenated). The `files` getter is sorted by
+ * path length (barrel `index.ts` last within a bucket).
+ *
+ * @example
+ * ```ts
  * const manager = new FileManager()
  * manager.upsert(myFile)
- * console.log(manager.files) // all stored files
+ * manager.files // sorted view
  * ```
  */
 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.
+   * Registers a callback invoked with the resolved {@link FileNode} on every
+   * `add` / `upsert`. Used by the build loop to track newly written files
+   * without keeping its own scan-based diff. Single subscriber by design —
+   * setting again replaces the previous callback. Pass `null` to detach.
    */
+  setOnUpsert(callback: ((file: FileNode) => void) | null): void;
   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).
+   * Releases all stored files. Called by the core after `kubb:build:end`.
+   */
+  dispose(): void;
+  [Symbol.dispose](): void;
+  /**
+   * All stored files in stable sort order (shortest path first, barrel files
+   * last within a length bucket). Returns a cached view — do not mutate.
    */
   get files(): Array<FileNode>;
 }
 //#endregion
-//#region src/PluginDriver.d.ts
+//#region src/KubbDriver.d.ts
 type Options = {
   hooks: AsyncEventEmitter<KubbHooks>;
 };
-declare class PluginDriver {
+declare class KubbDriver {
   #private;
   readonly config: Config;
   readonly options: Options;
@@ -429,17 +1298,17 @@ declare class PluginDriver {
    *
    * @example
    * ```ts
-   * PluginDriver.getMode('src/gen/types.ts')  // 'single'
-   * PluginDriver.getMode('src/gen/types')     // 'split'
+   * KubbDriver.getMode('src/gen/types.ts')  // 'single'
+   * KubbDriver.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.
+   * The streaming `InputStreamNode` produced by the adapter.
+   * Always set after adapter setup — parse-only adapters are wrapped automatically.
    */
-  inputNode: InputNode | undefined;
-  adapter: Adapter | undefined;
+  inputNode: InputStreamNode | null;
+  adapter: Adapter | null;
   /**
    * Central file store for all generated files.
    * Plugins should use `this.addFile()` / `this.upsertFile()` (via their context) to
@@ -448,23 +1317,8 @@ declare class PluginDriver {
   readonly fileManager: FileManager;
   readonly plugins: Map<string, NormalizedPlugin>;
   constructor(config: Config, options: Options);
+  setup(): Promise<void>;
   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.
@@ -486,7 +1340,7 @@ declare class PluginDriver {
    *
    * Call this method inside `addGenerator()` (in `kubb:plugin:setup`) to wire up a generator.
    */
-  registerGenerator(pluginName: string, gen: Generator): void;
+  registerGenerator(pluginName: string, gen: Generator$1): void;
   /**
    * Returns `true` when at least one generator was registered for the given plugin
    * via `addGenerator()` in `kubb:plugin:setup` (event-based path).
@@ -494,7 +1348,24 @@ declare class PluginDriver {
    * 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;
+  hasEventGenerators(pluginName: string): boolean;
+  /**
+   * Runs the full plugin pipeline. Returns timings/failures collected so far even
+   * when an outer hook throws — the orchestrator preserves partial state by capturing
+   * the error into `error` instead of propagating.
+   */
+  run({
+    storage
+  }: {
+    storage: Storage;
+  }): Promise<{
+    failedPlugins: Set<{
+      plugin: Plugin;
+      error: Error;
+    }>;
+    pluginTimings: Map<string, number>;
+    error?: Error;
+  }>;
   /**
    * Unregisters all plugin lifecycle listeners from the shared event emitter.
    * Called at the end of a build to prevent listener leaks across repeated builds.
@@ -502,6 +1373,7 @@ declare class PluginDriver {
    * @internal
    */
   dispose(): void;
+  [Symbol.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`
@@ -526,407 +1398,194 @@ declare class PluginDriver {
   requirePlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(pluginName: string): Plugin<TOptions>;
 }
 //#endregion
-//#region src/createKubb.d.ts
-/**
- * Full output produced by a successful or failed build.
- */
-type BuildOutput = {
-  /**
-   * Plugins that threw during installation, paired with the caught error.
-   */
-  failedPlugins: Set<{
-    plugin: Plugin;
-    error: Error;
-  }>;
-  files: Array<FileNode>;
-  driver: PluginDriver;
-  /**
-   * Elapsed time in milliseconds for each plugin, keyed by plugin name.
-   */
-  pluginTimings: Map<string, number>;
-  error?: Error;
-  /**
-   * Raw generated source, keyed by absolute file path.
-   */
-  sources: Map<string, string>;
-};
-type CreateKubbOptions = {
-  hooks?: AsyncEventEmitter<KubbHooks>;
-};
-/**
- * Creates a Kubb instance bound to a single config entry.
- *
- * 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()`.
- *
- * @example
- * ```ts
- * const kubb = createKubb(userConfig)
- *
- * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
- *   console.log(`${plugin.name} completed in ${duration}ms`)
- * })
- *
- * const { files, failedPlugins } = await kubb.safeBuild()
- * ```
- */
-declare function createKubb(userConfig: UserConfig, options?: CreateKubbOptions): Kubb$1;
-//#endregion
-//#region src/Kubb.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 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>;
-};
+//#region src/defineGenerator.d.ts
 /**
- * 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')
- * })
+ * Context object passed to generator `schema`, `operation`, and `operations` methods.
  *
- * hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
- *   console.log(`Plugin ${plugin.name} completed in ${duration}ms`)
- * })
- * ```
+ * 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.
  */
-interface KubbHooks {
-  /**
-   * Fires at the start of the Kubb lifecycle, before code generation begins.
-   */
-  'kubb:lifecycle:start': [ctx: KubbLifecycleStartContext];
-  /**
-   * Fires at the end of the Kubb lifecycle, after all code generation completes.
-   */
-  'kubb:lifecycle:end': [];
-  /**
-   * Fires when configuration loading starts.
-   */
-  'kubb:config:start': [];
-  /**
-   * Fires when configuration loading completes.
-   */
-  'kubb:config:end': [ctx: KubbConfigEndContext];
-  /**
-   * Fires when code generation starts.
-   */
-  'kubb:generation:start': [ctx: KubbGenerationStartContext];
-  /**
-   * Fires when code generation completes.
-   */
-  'kubb:generation:end': [ctx: KubbGenerationEndContext];
-  /**
-   * Fires with a generation summary including summary lines, title, and success status.
-   */
-  'kubb:generation:summary': [ctx: KubbGenerationSummaryContext];
-  /**
-   * Fires when code formatting starts (e.g., Biome or Prettier).
-   */
-  'kubb:format:start': [];
-  /**
-   * Fires when code formatting completes.
-   */
-  'kubb:format:end': [];
-  /**
-   * Fires when linting starts.
-   */
-  'kubb:lint:start': [];
-  /**
-   * Fires when linting completes.
-   */
-  'kubb:lint:end': [];
-  /**
-   * Fires when plugin hooks execution starts.
-   */
-  'kubb:hooks:start': [];
-  /**
-   * Fires when plugin hooks execution completes.
-   */
-  'kubb:hooks:end': [];
-  /**
-   * Fires when a single hook executes (e.g., format or lint). The callback is invoked when the command finishes.
-   */
-  'kubb:hook:start': [ctx: KubbHookStartContext];
-  /**
-   * Fires when a single hook execution completes.
-   */
-  'kubb:hook:end': [ctx: KubbHookEndContext];
-  /**
-   * Fires when a new Kubb version is available.
-   */
-  'kubb:version:new': [ctx: KubbVersionNewContext];
-  /**
-   * Informational message event.
-   */
-  'kubb:info': [ctx: KubbInfoContext];
-  /**
-   * Error event, fired when an error occurs during generation.
-   */
-  'kubb:error': [ctx: KubbErrorContext];
+type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+  config: Config;
   /**
-   * Success message event.
+   * Absolute path to the current plugin's output directory.
    */
-  'kubb:success': [ctx: KubbSuccessContext];
+  root: string;
   /**
-   * Warning message event.
+   * Determine output mode based on the output config.
+   * Returns `'single'` when `output.path` is a file, `'split'` for a directory.
    */
-  'kubb:warn': [ctx: KubbWarnContext];
+  getMode: (output: {
+    path: string;
+  }) => 'single' | 'split';
+  driver: KubbDriver;
   /**
-   * Debug event for detailed logging with timestamp and optional filename.
+   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
    */
-  'kubb:debug': [ctx: KubbDebugContext];
+  getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined;
+  getPlugin(name: string): Plugin | undefined;
   /**
-   * Fires when file processing starts with the list of files to process.
+   * Get a plugin by name, throws an error if not found.
    */
-  'kubb:files:processing:start': [ctx: KubbFilesProcessingStartContext];
+  requirePlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]>;
+  requirePlugin(name: string): Plugin;
   /**
-   * Fires for each file with progress updates: processed count, total, percentage, and file details.
+   * Get a resolver by plugin name, typed via `Kubb.PluginRegistry` when registered.
    */
-  'kubb:file:processing:update': [ctx: KubbFileProcessingUpdateContext];
+  getResolver<TName extends keyof Kubb.PluginRegistry>(name: TName): Kubb.PluginRegistry[TName]['resolver'];
+  getResolver(name: string): Resolver;
   /**
-   * Fires when file processing completes with the list of processed files.
+   * Add files only if they don't exist.
    */
-  'kubb:files:processing:end': [ctx: KubbFilesProcessingEndContext];
+  addFile: (...file: Array<FileNode>) => Promise<void>;
   /**
-   * Fires when a plugin starts execution.
+   * Merge sources into the same output file.
    */
-  'kubb:plugin:start': [ctx: KubbPluginStartContext];
+  upsertFile: (...file: Array<FileNode>) => Promise<void>;
+  hooks: AsyncEventEmitter<KubbHooks>;
   /**
-   * Fires when a plugin completes execution. Duration measured in milliseconds.
+   * The current plugin instance.
    */
-  'kubb:plugin:end': [ctx: KubbPluginEndContext];
+  plugin: Plugin<TOptions>;
   /**
-   * Fires once before plugins execute — allowing plugins to register generators, configure resolvers/transformers/renderers, or inject files.
+   * The current plugin's resolver.
    */
-  'kubb:plugin:setup': [ctx: KubbPluginSetupContext];
+  resolver: TOptions['resolver'];
   /**
-   * Fires before the plugin execution loop begins. The adapter has already parsed the source and `inputNode` is available.
+   * The current plugin's transformer.
    */
-  'kubb:build:start': [ctx: KubbBuildStartContext];
+  transformer: Visitor | undefined;
   /**
-   * 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.
+   * Emit a warning.
    */
-  'kubb:plugins:end': [ctx: KubbPluginsEndContext];
+  warn: (message: string) => void;
   /**
-   * Fires after all files write to disk.
+   * Emit an error.
    */
-  'kubb:build:end': [ctx: KubbBuildEndContext];
+  error: (error: string | Error) => void;
   /**
-   * Fires for each schema node during AST traversal. Generator listeners respond to this.
+   * Emit an info message.
    */
-  'kubb:generate:schema': [node: SchemaNode, ctx: GeneratorContext];
+  info: (message: string) => void;
   /**
-   * Fires for each operation node during AST traversal. Generator listeners respond to this.
+   * Open the current input node in Kubb Studio.
    */
-  'kubb:generate:operation': [node: OperationNode, ctx: GeneratorContext];
+  openInStudio: (options?: DevtoolsOptions) => Promise<void>;
   /**
-   * Fires once after all operations traverse with the full collected array. Batch generator listeners respond to this.
+   * The configured adapter instance.
    */
-  '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: {
-     *         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 {}
-  }
-}
-//#endregion
-//#region src/defineMiddleware.d.ts
-/**
- * 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 Middleware = {
+  adapter: Adapter;
   /**
-   * Unique identifier for this middleware.
+   * Document metadata from the adapter — title, version, base URL, and pre-computed
+   * schema index fields (`circularNames`, `enumNames`).
    */
-  name: string;
+  meta: InputMeta;
   /**
-   * 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.
+   * Resolved options after exclude/include/override filtering.
    */
-  hooks: { [K in keyof KubbHooks]?: (...args: KubbHooks[K]) => void | Promise<void> };
+  options: TOptions['resolvedOptions'];
 };
 /**
- * Creates a middleware factory using the hook-style `hooks` API.
+ * Declares a named generator unit that walks the AST and emits files.
  *
- * 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.
+ * Each method (`schema`, `operation`, `operations`) is called for the matching node type.
+ * Each method returns `TElement | Array<FileNode> | undefined | null`. JSX-based generators require a `renderer` factory.
+ * Return `Array<FileNode>` directly or call `ctx.upsertFile()` manually and return `undefined` or `null` to bypass rendering.
  *
- * @note The factory can accept typed options. See examples for using options and per-build state patterns.
+ * @note Generators are consumed by plugins and registered via `ctx.addGenerator()` in `kubb:plugin:setup`.
  *
  * @example
  * ```ts
- * import { defineMiddleware } from '@kubb/core'
+ * import { defineGenerator } from '@kubb/core'
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
  *
- * // Stateless middleware
- * export const logMiddleware = defineMiddleware(() => ({
- *   name: 'log-middleware',
- *   hooks: {
- *     'kubb:build:end'({ files }) {
- *       console.log(`Build complete with ${files.length} files`)
- *     },
+ * 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>
  *   },
- * }))
- *
- * // 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 defineMiddleware<TOptions extends object = object>(factory: (options: TOptions) => Middleware): (options?: TOptions) => Middleware;
-//#endregion
-//#region src/defineParser.d.ts
-type PrintOptions = {
-  extname?: FileNode['extname'];
-};
-type Parser<TMeta extends object = any> = {
+type Generator$1<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown> = {
+  /**
+   * Used in diagnostic messages and debug output.
+   */
   name: string;
   /**
-   * File extensions this parser handles.
-   * Use `undefined` to create a catch-all fallback parser.
+   * Optional renderer factory that produces a {@link Renderer} for each render cycle.
    *
-   * @example Handled extensions
-   * `['.ts', '.js']`
+   * 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> },
+   * })
+   * ```
    */
-  extNames: Array<FileNode['extname']> | undefined;
+  renderer?: RendererFactory<TElement> | null;
+  /**
+   * Called for each schema node in the AST walk.
+   * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
+   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
+   */
+  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>;
+  /**
+   * Called for each operation node in the AST walk.
+   * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
+   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
+   */
+  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>;
   /**
-   * Convert a resolved file to a string.
+   * Called once after all operations have been walked.
+   * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
+   * plus `ctx.options` with the plugin-level options for the batch call.
    */
-  parse(file: FileNode<TMeta>, options?: PrintOptions): Promise<string> | string;
+  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>;
 };
 /**
- * Defines a parser with type safety. Creates parsers that transform generated files to strings based on their extension.
+ * Defines a generator: a unit of work that runs during the plugin's AST walk
+ * and produces files. Plugins register generators via `ctx.addGenerator()`
+ * inside `kubb:plugin:setup`.
  *
- * @note Call the returned factory with optional options to instantiate the parser.
+ * The returned object is the input as-is, but with `this` types preserved so
+ * `schema`/`operation`/`operations` methods are correctly typed against the
+ * plugin's `PluginFactoryOptions`. Renderer elements and `FileNode[]` returns
+ * are both handled by the runtime — pick whichever style fits.
  *
- * @example
- * ```ts
- * import { defineParser } from '@kubb/core'
+ * @example JSX-based schema generator
+ * ```tsx
+ * import { defineGenerator } from '@kubb/core'
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
  *
- * 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 typeGenerator = defineGenerator({
+ *   name: 'typescript',
+ *   renderer: jsxRenderer,
+ *   schema(node, ctx) {
+ *     return (
+ *       <File path={`${ctx.root}/${node.name}.ts`}>
+ *         <Type node={node} resolver={ctx.resolver} />
+ *       </File>
+ *     )
  *   },
  * })
  * ```
  */
-declare function defineParser<TMeta extends object = any>(parser: Parser<TMeta>): Parser<TMeta>;
+declare function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(generator: Generator$1<TOptions, TElement>): Generator$1<TOptions, TElement>;
 //#endregion
-//#region src/types.d.ts
+//#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`
@@ -972,88 +1631,6 @@ type InputData = {
   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;
-};
-/**
- * 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>;
-};
-type DevtoolsOptions = {
-  /**
-   * Open the AST inspector in Kubb Studio (`/ast`). Defaults to the main Studio page.
-   * @default false
-   */
-  ast?: boolean;
-};
 /**
  * Build configuration for Kubb code generation.
  *
@@ -1079,30 +1656,37 @@ type Config<TInput = Input> = {
    */
   name?: string;
   /**
-   * Project root directory, absolute or relative to the config file.
-   * @default process.cwd()
+   * Project root directory, absolute or relative to the config file. Already
+   * resolved on the `Config` instance — see `UserConfig` for the optional
+   * form that defaults to `process.cwd()`.
    */
   root: string;
   /**
-   * 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`.
+   * Parsers that convert generated files into strings. Each parser handles a
+   * set of file extensions; a fallback parser handles anything else.
+   *
+   * Already resolved on the `Config` instance — see `UserConfig` for the
+   * optional form that defaults to `[parserTs, parserTsx]`.
    *
-   * @default [parserTs] from `@kubb/parser-ts`
    * @example
    * ```ts
-   * import { parserTs, tsxParser } from '@kubb/parser-ts'
+   * import { defineConfig } from 'kubb'
+   * import { parserTs, parserTsx } from '@kubb/parser-ts'
+   *
    * export default defineConfig({
-   *   parsers: [parserTs, tsxParser],
+   *   parsers: [parserTs, parserTsx],
    * })
    * ```
    */
   parsers: Array<Parser>;
   /**
-   * Adapter that parses input files into the universal `InputNode` representation.
+   * Adapter that parses input files into the universal AST representation.
    * Use `@kubb/adapter-oas` for OpenAPI/Swagger or `@kubb/adapter-asyncapi` for other formats.
    *
+   * 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.
+   *
    * @example
    * ```ts
    * import { adapterOas } from '@kubb/adapter-oas'
@@ -1112,12 +1696,13 @@ type Config<TInput = Input> = {
    * })
    * ```
    */
-  adapter: Adapter;
+  adapter?: Adapter;
   /**
    * 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.
    */
-  input: TInput;
+  input?: TInput;
   output: {
     /**
      * Output directory for generated files, absolute or relative to `root`.
@@ -1146,13 +1731,6 @@ type Config<TInput = Input> = {
      * ```
      */
     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.
      *
@@ -1226,7 +1804,7 @@ type Config<TInput = Input> = {
      * ```
      */
     override?: boolean;
-  } & ExtractRegistryKey<Kubb.ConfigOptionsRegistry, 'output'>;
+  } & ExtractRegistryKey<Kubb$1.ConfigOptionsRegistry, 'output'>;
   /**
    * Storage backend that controls where and how generated files are persisted.
    *
@@ -1247,7 +1825,7 @@ type Config<TInput = Input> = {
    *
    * @see {@link Storage} interface for implementing custom backends.
    */
-  storage?: Storage;
+  storage: Storage;
   /**
    * Plugins that execute during the build to generate code and transform the AST.
    *
@@ -1288,19 +1866,6 @@ type Config<TInput = Input> = {
    * @see {@link defineMiddleware} to create custom middleware.
    */
   middleware?: Array<Middleware>;
-  /**
-   * Default renderer factory used by all plugins and generators.
-   * Resolution chain: `generator.renderer` → `plugin.renderer` → `config.renderer` → `undefined` (raw FileNode[] mode).
-   *
-   * @example
-   * ```ts
-   * import { jsxRenderer } from '@kubb/renderer-jsx'
-   * export default defineConfig({
-   *   renderer: jsxRenderer,
-   *   plugins: [pluginTs(), pluginZod()],
-   * })
-   * ```
-   */
   /**
    * Renderer that converts generated AST nodes to code strings.
    *
@@ -1320,7 +1885,7 @@ type Config<TInput = Input> = {
   /**
    * Kubb Studio cloud integration settings.
    *
-   * Kubb Studio (https://studio.kubb.dev) is a web-based IDE for managing API specs and generated code.
+   * 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
@@ -1333,7 +1898,7 @@ type Config<TInput = Input> = {
   devtools?: true | {
     /**
      * Override the Kubb Studio base URL.
-     * @default 'https://studio.kubb.dev'
+     * @default 'https://kubb.studio'
      */
     studioUrl?: typeof DEFAULT_STUDIO_URL | (string & {});
   };
@@ -1361,788 +1926,576 @@ type Config<TInput = Input> = {
      * 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>;
-  };
-};
-/**
- * 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'> & {
-  /**
-   * Project root directory, absolute or relative to the config file location.
-   *
-   * Used as the base path for `root`-relative paths (e.g., `output.path`, file paths in hooks).
-   *
-   * @default process.cwd()
-   * @example
-   * ```ts
-   * root: '/home/user/my-project'
-   * root: './my-project'  // relative to config file
-   * ```
-   */
-  root?: string;
-  /**
-   * Custom parsers that convert generated AST nodes to strings (TypeScript, JSON, markdown, etc.).
-   *
-   * 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.
-   *
-   * @default [parserTs]  // from @kubb/parser-ts
-   * @example
-   * ```ts
-   * import { parserTs } from '@kubb/parser-ts'
-   * import { parserJsonSchema } from '@kubb/parser-json-schema'
-   *
-   * parsers: [parserTs(), parserJsonSchema()]
-   * ```
-   *
-   * @see {@link Parser} to implement a custom parser.
-   */
-  parsers?: Array<Parser>;
-  /**
-   * Adapter that parses your API specification (OpenAPI, GraphQL, AsyncAPI, etc.) into Kubb's universal AST.
-   *
-   * 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.
-   *
-   * @default new OasAdapter()  // from @kubb/adapter-oas
-   * @example
-   * ```ts
-   * import { Oas } from '@kubb/adapter-oas'
-   *
-   * adapter: new Oas({ apiVersion: '3.0.0' })
-   * ```
-   *
-   * @see {@link Adapter} to implement a custom adapter for GraphQL or other formats.
-   */
-  adapter?: Adapter;
-  /**
-   * 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.).
-   *
-   * @default []  // no plugins (useful for setup/testing)
-   * @example
-   * ```ts
-   * plugins: [
-   *   pluginTs({ output: { path: './src/gen' } }),
-   *   pluginZod({ output: { path: './src/gen' } }),
-   * ]
-   * ```
-   *
-   * @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'];
+     * ```ts
+     * done: 'prettier --write "./src/gen"'
+     * done: ['prettier --write "./src/gen"', 'eslint --fix "./src/gen"']
+     * ```
+     */
+    done?: string | Array<string>;
+  };
 };
 /**
- * Output configuration for generated files.
+ * 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 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);
+type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter' | 'storage'> & {
   /**
-   * Text or function appended to every generated file.
-   * When a function, receives the current `InputNode` and returns a string.
+   * Project root directory, absolute or relative to the config file location.
+   * @default process.cwd()
    */
-  footer?: string | ((node?: InputNode) => string);
+  root?: string;
   /**
-   * Whether to override existing external files if they already exist.
-   * @default false
+   * Custom parsers that convert generated AST nodes to strings (TypeScript, JSON, markdown, etc.).
+   * @default [parserTs]  // from `@kubb/parser-ts`
    */
-  override?: boolean;
-} & ExtractRegistryKey<Kubb.PluginOptionsRegistry, 'output'>;
-type Group = {
+  parsers?: Array<Parser>;
   /**
-   * How to group files into subdirectories.
-   * - `'tag'` — group by OpenAPI tags
-   * - `'path'` — group by OpenAPI paths
+   * Adapter that parses your API specification into Kubb's universal AST.
+   * When omitted, Kubb runs in plugin-only mode.
    */
-  type: 'tag' | 'path';
+  adapter?: Adapter;
   /**
-   * Function that returns the subdirectory name for a group value.
-   * Defaults to `${camelCase(group)}Controller` for tags, first path segment for paths.
+   * Plugins that execute during the build to generate code and transform the AST.
+   * @default []
    */
-  name?: (context: {
-    group: string;
-  }) => string;
-};
-type LoggerOptions = {
+  plugins?: Array<Plugin>;
   /**
-   * Log level for output verbosity.
-   * @default 3
+   * Storage backend that controls where and how generated files are persisted.
+   * @default fsStorage()
    */
-  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>;
+  storage?: Storage;
 };
-type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Logger<TOptions>;
+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:plugin:setup` handler.
- * Provides methods to register generators, configure resolvers, transformers, and renderers.
+ * Lifecycle events emitted during Kubb code generation.
+ * Attach listeners before calling `setup()` or `build()` to observe and react to build progress.
+ *
+ * @example
+ * ```ts
+ * kubb.hooks.on('kubb:lifecycle:start', () => {
+ *   console.log('Starting Kubb generation')
+ * })
+ *
+ * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
+ *   console.log(`${plugin.name} completed in ${duration}ms`)
+ * })
+ * ```
  */
-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.
-   */
-  setResolver(resolver: Partial<TFactory['resolver']>): void;
-  /**
-   * Set the AST transformer to pre-process nodes before they reach generators.
-   */
-  setTransformer(visitor: Visitor): void;
-  /**
-   * Set the renderer factory to process JSX elements from generators.
-   */
-  setRenderer(renderer: RendererFactory): void;
-  /**
-   * Set resolved options merged into the normalized plugin's `options`.
-   * Call this in `kubb:plugin:setup` to provide options generators need.
-   */
-  setOptions(options: TFactory['resolvedOptions']): void;
-  /**
-   * Inject a raw file into the build output, bypassing the generation pipeline.
-   */
-  injectFile(userFileNode: UserFileNode): void;
-  /**
-   * Merge a partial config update into the current build configuration.
-   */
-  updateConfig(config: Partial<Config>): void;
+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:files:processing:update': [ctx: KubbFilesProcessingUpdateContext];
+  '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 = {
   /**
-   * The resolved build configuration at setup time.
+   * Resolved configuration for this build.
    */
   config: Config;
   /**
-   * The plugin's user-provided options.
+   * Adapter that parsed the input into the universal AST.
    */
-  options: TFactory['options'];
-};
-/**
- * Context for hook-style plugin `kubb:build:start` handler.
- * Fires immediately before the plugin execution loop begins.
- */
-type KubbBuildStartContext = {
-  config: Config;
   adapter: Adapter;
-  inputNode: InputNode;
   /**
-   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
+   * Metadata about the parsed document (title, version, base URL, circular schema names, enum names).
+   * To observe individual schemas and operations use the `kubb:generate:schema` / `kubb:generate:operation` hooks.
    */
-  getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined;
+  meta: InputMeta | undefined;
+  /**
+   * Looks up a registered plugin by name, typed by the plugin registry.
+   */
+  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.
+   * Snapshot of all files accumulated so far.
    */
   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`.
+   * Adds or merges one or more files into the file manager.
    */
   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 = {
+  /**
+   * Resolved configuration for this build.
+   */
   config: Config;
   /**
-   * All files currently in the file manager (lazy snapshot).
+   * Snapshot of all files accumulated across all plugins.
    */
   readonly files: ReadonlyArray<FileNode>;
   /**
-   * Upsert files into the file manager.
-   * Files added here are included in the write pass.
+   * Adds or merges one or more files into the file manager.
    */
   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 = {
+  /**
+   * All files generated during this build.
+   */
   files: Array<FileNode>;
+  /**
+   * Resolved configuration for this build.
+   */
   config: Config;
+  /**
+   * Absolute path to the output directory.
+   */
   outputDir: string;
 };
 type KubbLifecycleStartContext = {
+  /**
+   * Current Kubb version string.
+   */
   version: string;
 };
 type KubbConfigEndContext = {
+  /**
+   * All resolved configs after defaults are applied.
+   */
   configs: Array<Config>;
 };
 type KubbGenerationStartContext = {
+  /**
+   * Resolved configuration for this generation run.
+   */
   config: Config;
 };
 type KubbGenerationEndContext = {
+  /**
+   * Resolved configuration for this generation run.
+   */
   config: Config;
-  files: Array<FileNode>;
-  sources: Map<string, string>;
+  /**
+   * Read-only view of the files written during this build.
+   * Reads go directly to `config.storage` — nothing extra is held in memory.
+   *
+   * @example Read a generated file
+   * `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 = {
+  /**
+   * Resolved configuration for this generation run.
+   */
   config: Config;
+  /**
+   * Plugins that threw during generation, paired with their errors.
+   */
   failedPlugins: Set<{
     plugin: Plugin;
     error: Error;
   }>;
+  /**
+   * `'success'` when all plugins completed without errors, `'failed'` otherwise.
+   */
   status: 'success' | 'failed';
+  /**
+   * High-resolution start time from `process.hrtime()`.
+   */
   hrStart: [number, number];
+  /**
+   * Total number of files created during this run.
+   */
   filesCreated: number;
+  /**
+   * Elapsed milliseconds per plugin, keyed by plugin name.
+   */
   pluginTimings?: Map<Plugin['name'], number>;
 };
 type KubbVersionNewContext = {
+  /**
+   * The installed Kubb version.
+   */
   currentVersion: string;
+  /**
+   * The newest available version on npm.
+   */
   latestVersion: string;
 };
 type KubbInfoContext = {
+  /**
+   * Human-readable info message.
+   */
   message: string;
+  /**
+   * Optional supplementary detail.
+   */
   info?: string;
 };
 type KubbErrorContext = {
+  /**
+   * The caught error.
+   */
   error: Error;
+  /**
+   * Optional structured metadata for additional context.
+   */
   meta?: Record<string, unknown>;
 };
 type KubbSuccessContext = {
+  /**
+   * Human-readable success message.
+   */
   message: string;
+  /**
+   * Optional supplementary detail.
+   */
   info?: string;
 };
 type KubbWarnContext = {
+  /**
+   * Human-readable warning message.
+   */
   message: string;
+  /**
+   * Optional supplementary detail.
+   */
   info?: string;
 };
 type KubbDebugContext = {
+  /**
+   * Timestamp when the debug entry was created.
+   */
   date: Date;
+  /**
+   * One or more log lines to emit.
+   */
   logs: Array<string>;
+  /**
+   * Optional source file name associated with this entry.
+   */
   fileName?: string;
 };
 type KubbFilesProcessingStartContext = {
+  /**
+   * Files about to be serialised and written.
+   */
   files: Array<FileNode>;
 };
-type KubbFileProcessingUpdateContext = {
+type KubbFileProcessingUpdate = {
   /**
-   * Number of files processed.
+   * Number of files processed so far in this batch.
    */
   processed: number;
   /**
-   * Total files to process.
+   * Total number of files in this batch.
    */
   total: number;
   /**
-   * Processing percentage (0–100).
+   * Completion percentage (`0`–`100`).
    */
   percentage: number;
   /**
-   * Optional source identifier.
+   * Serialised file content, or `undefined` when the file produced no output.
    */
   source?: string;
   /**
-   * The file being processed.
+   * The file that was just processed.
    */
   file: FileNode;
   /**
-   * The current build configuration.
+   * Resolved configuration for this build.
    */
   config: Config;
 };
-type KubbFilesProcessingEndContext = {
-  files: Array<FileNode>;
-};
-type KubbPluginStartContext = {
-  plugin: NormalizedPlugin;
-};
-type KubbPluginEndContext = {
-  plugin: NormalizedPlugin;
-  duration: number;
-  success: boolean;
-  error?: Error;
-  config: Config;
+type KubbFilesProcessingUpdateContext = {
   /**
-   * Returns all files currently in the file manager (lazy snapshot).
-   * Includes files added by plugins that have already run.
+   * All files processed in this flush chunk.
    */
-  readonly files: ReadonlyArray<FileNode>;
+  files: Array<KubbFileProcessingUpdate>;
+};
+type KubbFilesProcessingEndContext = {
   /**
-   * Upsert one or more files into the file manager.
+   * All files that were serialised in this batch.
    */
-  upsertFile: (...files: Array<FileNode>) => void;
+  files: Array<FileNode>;
 };
 type KubbHookStartContext = {
-  id?: string;
-  command: string;
-  args?: readonly string[];
-};
-type KubbHookEndContext = {
-  id?: string;
-  command: string;
-  args?: readonly string[];
-  success: boolean;
-  error: Error | null;
-};
-type ByTag = {
   /**
-   * Filter by OpenAPI `tags` field. Matches one or more tags assigned to operations.
+   * Optional identifier for correlating start/end events.
    */
-  type: 'tag';
+  id?: string;
   /**
-   * Tag name to match (case-sensitive). Can be a literal string or regex pattern.
+   * The shell command that is about to run.
    */
-  pattern: string | RegExp;
-};
-type ByOperationId = {
+  command: string;
   /**
-   * Filter by OpenAPI `operationId` field. Each operation (GET, POST, etc.) has a unique identifier.
+   * Parsed argument list, when available.
    */
-  type: 'operationId';
+  args?: ReadonlyArray<string>;
+};
+type KubbHookEndContext = {
   /**
-   * Operation ID to match (case-sensitive). Can be a literal string or regex pattern.
+   * Optional identifier matching the corresponding `kubb:hook:start` event.
    */
-  pattern: string | RegExp;
-};
-type ByPath = {
+  id?: string;
   /**
-   * Filter by OpenAPI `path` (URL endpoint). Useful to group or filter by service segments like `/pets`, `/users`, etc.
+   * The shell command that ran.
    */
-  type: 'path';
+  command: string;
   /**
-   * URL path to match (case-sensitive). Can be a literal string or regex pattern. Matches against the full path.
+   * Parsed argument list, when available.
    */
-  pattern: string | RegExp;
-};
-type ByMethod = {
+  args?: ReadonlyArray<string>;
   /**
-   * Filter by HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'head'`, `'options'`.
+   * `true` when the command exited with code `0`.
    */
-  type: 'method';
+  success: boolean;
   /**
-   * HTTP method to match (case-insensitive when using string, or regex for dynamic matching).
+   * Error thrown by the command, or `null` on success.
    */
-  pattern: HttpMethod | RegExp;
+  error: Error | null;
 };
-type BySchemaName = {
+/**
+ * CLI options derived from command-line flags.
+ */
+type CLIOptions = {
   /**
-   * Filter by schema component name (TypeScript or JSON schema). Matches schemas in `#/components/schemas`.
+   * Path to the Kubb config file.
    */
-  type: 'schemaName';
+  config?: string;
   /**
-   * Schema name to match (case-sensitive). Can be a literal string or regex pattern.
+   * OpenAPI input path passed as the positional argument to `kubb generate`.
+   * Overrides `config.input.path` when set.
    */
-  pattern: string | RegExp;
-};
-type ByContentType = {
+  input?: string;
   /**
-   * Filter by response or request content type: `'application/json'`, `'application/xml'`, etc.
+   * Re-run generation whenever input files change.
    */
-  type: 'contentType';
+  watch?: boolean;
   /**
-   * Content type to match (case-sensitive). Can be a literal string or regex pattern.
+   * Controls how much output the CLI prints.
+   *
+   * @default 'info'
    */
-  pattern: string | RegExp;
+  logLevel?: 'silent' | 'info' | 'verbose' | 'debug';
 };
 /**
- * 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
- *   }
- * ]
- * ```
+ * All accepted forms of a Kubb configuration.
+ * Accepts `Config`/`Config[]`/promise or a factory (optionally receiving `TCliOptions`.
  */
-type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
-  options: Partial<TOptions>;
-};
+type PossibleConfig<TCliOptions = undefined> = PossiblePromise<Config | Array<Config>> | ((...args: [TCliOptions] extends [undefined] ? [] : [TCliOptions]) => PossiblePromise<Config | Array<Config>>);
 /**
- * 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'
- * ```
+ * Full output produced by a successful or failed build.
  */
-type ResolverPathParams = {
-  baseName: FileNode['baseName'];
-  pathMode?: 'single' | 'split';
+type BuildOutput = {
   /**
-   * Tag value used when `group.type === 'tag'`.
+   * Plugins that threw during generation, paired with their errors.
    */
-  tag?: string;
+  failedPlugins: Set<{
+    plugin: Plugin;
+    error: Error;
+  }>;
   /**
-   * Path value used when `group.type === 'path'`.
+   * All files generated during this build.
    */
-  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;
+  files: Array<FileNode>;
   /**
-   * Plugin name used to populate `meta.pluginName` on the resolved file.
+   * The plugin driver that orchestrated this build.
    */
-  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'];
+  driver: KubbDriver;
   /**
-   * Tag value used when `group.type === 'tag'`.
+   * Elapsed milliseconds per plugin, keyed by plugin name.
    */
-  tag?: string;
+  pluginTimings: Map<string, number>;
   /**
-   * Path value used when `group.type === 'path'`.
+   * Top-level error when the build threw before completing, otherwise `undefined`.
    */
-  path?: string;
+  error?: Error;
+  /**
+   * Read-only view of every file written during this build.
+   * Reads go straight to `config.storage` — nothing extra is held in memory.
+   *
+   * @example Read a generated file
+   * `const code = await buildOutput.storage.getItem('/src/gen/pet.ts')`
+   *
+   * @example List all generated file paths
+   * `const paths = await buildOutput.storage.getKeys()`
+   */
+  storage: Storage;
 };
 /**
- * Context passed to `Resolver.resolveBanner` and `Resolver.resolveFooter`.
+ * Type guard to check if a given config has an `input.path`.
+ */
+declare function isInputPath(config: UserConfig | undefined): config is UserConfig<InputPath> & {
+  input: InputPath;
+};
+declare function isInputPath(config: Config | undefined): config is Config<InputPath> & {
+  input: InputPath;
+};
+type CreateKubbOptions = {
+  hooks?: AsyncEventEmitter<KubbHooks>;
+};
+/**
+ * Kubb code-generation instance bound to a single config entry. Resolves the user
+ * config during `setup()` and shares `hooks`, `storage`, `driver`, and `config` across
+ * the `setup → build` lifecycle.
  *
- * `output` is optional — not every plugin configures a banner/footer.
- * `config` carries the global Kubb config, used to derive the default Kubb banner.
+ * Attach event listeners to `.hooks` before calling `setup()` or `build()`.
  *
  * @example
  * ```ts
- * resolver.resolveBanner(inputNode, { output: { banner: '// generated' }, config })
- * // → '// generated'
+ * const kubb = createKubb(userConfig)
+ * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => console.log(plugin.name, duration))
+ * const { files, failedPlugins } = await kubb.safeBuild()
  * ```
  */
-type ResolveBannerContext = {
-  output?: Pick<Output, 'banner' | 'footer'>;
-  config: Config;
-};
-/**
- * CLI options derived from command-line flags.
- */
-type CLIOptions = {
+declare class Kubb$1 {
+  #private;
+  readonly hooks: AsyncEventEmitter<KubbHooks>;
+  constructor(userConfig: UserConfig, options?: CreateKubbOptions);
+  get storage(): Storage;
+  get driver(): KubbDriver;
+  get config(): Config;
   /**
-   * Path to `kubb.config.js`.
+   * Resolves config and initializes the driver. `build()` calls this automatically.
    */
-  config?: string;
+  setup(): Promise<void>;
   /**
-   * Enable watch mode for input files.
+   * Runs the full pipeline and throws on any plugin error.
+   * Automatically calls `setup()` if needed.
    */
-  watch?: boolean;
+  build(): Promise<BuildOutput>;
   /**
-   * Logging verbosity for CLI usage.
-   * @default 'silent'
+   * Runs the full pipeline and captures errors in `BuildOutput` instead of throwing.
+   * Automatically calls `setup()` if needed.
    */
-  logLevel?: 'silent' | 'info' | 'debug';
-};
+  safeBuild(): Promise<BuildOutput>;
+  dispose(): void;
+  [Symbol.dispose](): void;
+}
 /**
- * All accepted forms of a Kubb configuration.
+ * Constructs a {@link Kubb} build orchestrator from a user config. Equivalent
+ * to `new Kubb(userConfig, options)` and the canonical public entry point.
+ *
+ * @example
+ * ```ts
+ * import { createKubb } from '@kubb/core'
+ * import { adapterOas } from '@kubb/adapter-oas'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ *
+ * const kubb = createKubb({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   adapter: adapterOas(),
+ *   plugins: [pluginTs()],
+ * })
  *
- * 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`.
+ * await kubb.build()
+ * ```
  */
-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-CC09VtBt.d.ts.map
+export { Resolver as $, createKubb as A, KubbPluginEndContext as B, KubbLifecycleStartContext as C, AdapterFactoryOptions as Ct, KubbWarnContext as D, AsyncEventEmitter as Dt, KubbVersionNewContext as E, logLevel as Et, KubbDriver as F, Override as G, KubbPluginStartContext as H, FileManager as I, definePlugin as J, Plugin as K, Exclude as L, Generator$1 as M, GeneratorContext as N, PossibleConfig as O, defineGenerator as P, ResolveOptionsContext as Q, Group as R, KubbInfoContext as S, Adapter as St, KubbSuccessContext as T, createAdapter as Tt, NormalizedPlugin as U, KubbPluginSetupContext as V, Output as W, ResolveBannerContext as X, BannerMeta as Y, ResolveBannerFile as Z, KubbGenerationStartContext as _, Storage as _t, InputPath as a, defineMiddleware as at, KubbHookStartContext as b, RendererFactory as bt, KubbBuildStartContext as c, LoggerOptions as ct, KubbErrorContext as d, FileProcessor as dt, ResolverContext as et, KubbFileProcessingUpdate as f, FileProcessorEvents as ft, KubbGenerationEndContext as g, DevtoolsOptions as gt, KubbFilesProcessingUpdateContext as h, defineParser as ht, InputData as i, Middleware as it, isInputPath as j, UserConfig as k, KubbConfigEndContext as l, UserLogger as lt, KubbFilesProcessingStartContext as m, Parser as mt, CLIOptions as n, ResolverPathParams as nt, Kubb$1 as o, Logger as ot, KubbFilesProcessingEndContext as p, ParsedFile as pt, PluginFactoryOptions as q, Config as r, defineResolver as rt, KubbBuildEndContext as s, LoggerContext as st, BuildOutput as t, ResolverFileParams as tt, KubbDebugContext as u, defineLogger as ut, KubbGenerationSummaryContext as v, createStorage as vt, KubbPluginsEndContext as w, AdapterSource as wt, KubbHooks as x, createRenderer as xt, KubbHookEndContext as y, Renderer as yt, Include as z };
+//# sourceMappingURL=createKubb-6zii1jo-.d.ts.map